@northguild/gmt 1.18.0 → 1.20.0

package/dist/utc/calculate/isBetweenUtc.js

@@ -1,5 +1,5 @@
 // fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";

package/dist/utc/calculate/maxUtc.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
 /**
  * Return the latest (maximum) of the given UTC datetime values.

package/dist/utc/calculate/minUtc.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
 /**
  * Return the earliest (minimum) of the given UTC datetime values.

package/dist/utc/calculate/roundUtc.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import type { FractionalDigit } from "../../types/index.js";
 /**
  * Round a UTC datetime string to the specified unit.

package/dist/utc/calculate/roundUtc.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { defaultFractionalDigits, isObject, resolveDateTimeUnit, } from "../../internal/index.js";
 import { isValidTimeUnit } from "../../plain/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";

package/dist/utc/calculate/setUtc.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import type { Overflow } from "../../types/index.js";
 /**
  * Return a UTC Instant string with the given `fields` set on `value`.
@@ -9,8 +9,20 @@ import type { Overflow } from "../../types/index.js";
  *   `addUtc()` calls field-by-field — see `setDate`'s doc for why order-independent field
  *   resolution matters.
  * - `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.
+ *   `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.
  * - There are no `disambiguation` or `offset` options (removed in 1.16.0): a UTC instant's wall
  *   clock is never ambiguous and its offset is always +00:00, so neither had anything to act on.
  * - Returns "" for invalid input.
@@ -24,9 +36,10 @@ import type { Overflow } from "../../types/index.js";
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }) // "2024-02-29T12:00:00Z" (constrain clamps to the last valid day)
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }, { overflow: "reject" }) // ""
  * @example setUtc("2024-03-10T12:00:00Z", {}) // "2024-03-10T12:00:00Z" (empty fields object is a no-op)
+ * @example setUtc("2024-03-10T12:00:00Z", { hour: "9" }) // "" (not converted)
  * @example setUtc("invalid", { hour: 9 }) // ""
  */
-export declare function setUtc(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+export declare function setUtc(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset" | "era" | "eraYear">, options?: {
     /**
      * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
      * so `month: 2` on Jan 31 is Feb 29/28 (TC39 Temporal); `"reject"` returns `""`.

package/dist/utc/calculate/setUtc.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { resolveOverflow } from "../../internal/index.js";
+import { Temporal } from "../../internal/temporal.js";
+import { DATE_TIME_FIELDS, readSetFields, resolveOverflow, } from "../../internal/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -11,8 +11,20 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   `addUtc()` calls field-by-field — see `setDate`'s doc for why order-independent field
  *   resolution matters.
  * - `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.
+ *   `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.
  * - There are no `disambiguation` or `offset` options (removed in 1.16.0): a UTC instant's wall
  *   clock is never ambiguous and its offset is always +00:00, so neither had anything to act on.
  * - Returns "" for invalid input.
@@ -26,6 +38,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }) // "2024-02-29T12:00:00Z" (constrain clamps to the last valid day)
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }, { overflow: "reject" }) // ""
  * @example setUtc("2024-03-10T12:00:00Z", {}) // "2024-03-10T12:00:00Z" (empty fields object is a no-op)
+ * @example setUtc("2024-03-10T12:00:00Z", { hour: "9" }) // "" (not converted)
  * @example setUtc("invalid", { hour: 9 }) // ""
  */
 export function setUtc(value, fields, options) {
@@ -39,11 +52,12 @@ export function setUtc(value, fields, options) {
         try {
             const instant = Temporal.Instant.from(value);
             const zoned = instant.toZonedDateTimeISO("UTC");
-            // 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.
-            const result = Object.keys(fields).length === 0
-                ? zoned
-                : zoned.with(fields, { overflow });
+            const set = readSetFields(fields, DATE_TIME_FIELDS);
+            if (set === null)
+                return "";
+            // Only the values readSetFields checked reach Temporal. An empty result sets nothing: a
+            // no-op here, where Temporal's with() would throw.
+            const result = Object.keys(set).length === 0 ? zoned : zoned.with(set, { overflow });
             return result.toInstant().toString();
         }
         catch {

package/dist/utc/calculate/sortUtc.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
 /**
  * Sort an array of UTC datetime values in ascending or descending order.

package/dist/utc/calculate/startOfQuarterForUtc.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidUtc } from "../validate/index.js";
 /**
  * Return the start of the quarter for a given UTC datetime string.

package/dist/utc/calculate/startOfUtc.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../../internal/temporal.js";
 import type { FractionalDigit } from "../../types/index.js";
 /**
  * Return the start of the specified date-time `unit` for a given UTC datetime string.

package/dist/utc/calculate/subtractUtc.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { Temporal } from "../../internal/temporal.js";
+import { readDurationUnits, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -26,17 +26,14 @@ export function subtractUtc(value, units, options) {
             return "";
         }
         const validUtc = isValidUtc(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validUtc || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validUtc || amounts === null) {
             return "";
         }
         try {
             const instant = Temporal.Instant.from(value);
             const zoned = instant.toZonedDateTimeISO("UTC");
-            const result = zoned.subtract(units, {
+            const result = zoned.subtract(amounts, {
                 overflow: resolveOverflow(options?.overflow),
             });
             return result.toInstant().toString();

package/dist/utc/compare/areUtcEqual.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidUtc } from "../validate/index.js";
 /**
  * Return whether `value1` and `value2` represent the same instant.

package/dist/utc/compare/areUtcEqualBy.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 /**
  * Compare two UTC ISO datetime strings for equality at a given unit.
  *
@@ -12,7 +12,7 @@ import { Temporal } from "@js-temporal/polyfill";
  *   digits cannot change which bucket a value is in. That ignored option was removed in 1.16.0; to
  *   compare more coarsely, pass a coarser unit (0 digits is `"second"`, 3 is `"millisecond"`).
  *
- * Mapping from date-fns:
+ * Migrating from date-fns:
  * - `isSameDay(a, b)` → `areUtcEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUtcEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUtcEqualBy(a, b, "year")`

package/dist/utc/compare/areUtcEqualBy.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidDateTimeUnit } from "../../plain/index.js";
 import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
@@ -18,7 +18,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   digits cannot change which bucket a value is in. That ignored option was removed in 1.16.0; to
  *   compare more coarsely, pass a coarser unit (0 digits is `"second"`, 3 is `"millisecond"`).
  *
- * Mapping from date-fns:
+ * Migrating from date-fns:
  * - `isSameDay(a, b)` → `areUtcEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUtcEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUtcEqualBy(a, b, "year")`

package/dist/utc/compare/isAfterUtc.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidUtc } from "../validate/index.js";
 /**
  * Return whether `value1` represents an instant strictly after `value2`.

package/dist/utc/compare/isBeforeUtc.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidUtc } from "../validate/index.js";
 /**
  * Return whether `value1` represents an instant strictly before `value2`.

package/dist/utc/convert/convertUtcToPlainDate.d.ts

@@ -2,6 +2,8 @@
  * Convert a UTC datetime string to a plain date string in the format "YYYY-MM-DD".
  *
  * - Converts to the `timeZone` option's zone before extracting the date.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it, so the result is always a string `isValidDate` accepts.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
@@ -9,13 +11,17 @@
  * @returns plain date string in "YYYY-MM-DD" format or "" on invalid input
  *
  * @example convertUtcToPlainDate("2024-02-29T00:00:00Z") // "2024-02-29"
- * @example convertUtcToPlainDate("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "2024-02-28"
+ * @example convertUtcToPlainDate("2024-02-29T00:00:00Z", { timeZone: "America/Sao_Paulo" }) // "2024-02-28"
  * @example convertUtcToPlainDate("invalid") // ""
+ * @example convertUtcToPlainDate("+010000-01-01T00:00:00Z") // "+010000-01-01" (a year past 9999 has a sign and six digits)
+ * @example convertUtcToPlainDate("1970-01-01T00:30:00Z", { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export declare function convertUtcToPlainDate(value: string, options?: {
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/utc/convert/convertUtcToPlainDate.js

@@ -1,12 +1,14 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { Temporal } from "@js-temporal/polyfill";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { Temporal } from "../../internal/temporal.js";
+import { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain date string in the format "YYYY-MM-DD".
  *
  * - Converts to the `timeZone` option's zone before extracting the date.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it, so the result is always a string `isValidDate` accepts.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
@@ -14,25 +16,26 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @returns plain date string in "YYYY-MM-DD" format or "" on invalid input
  *
  * @example convertUtcToPlainDate("2024-02-29T00:00:00Z") // "2024-02-29"
- * @example convertUtcToPlainDate("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "2024-02-28"
+ * @example convertUtcToPlainDate("2024-02-29T00:00:00Z", { timeZone: "America/Sao_Paulo" }) // "2024-02-28"
  * @example convertUtcToPlainDate("invalid") // ""
+ * @example convertUtcToPlainDate("+010000-01-01T00:00:00Z") // "+010000-01-01" (a year past 9999 has a sign and six digits)
+ * @example convertUtcToPlainDate("1970-01-01T00:30:00Z", { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export function convertUtcToPlainDate(value, options) {
     try {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const timeZone = normalizeTimeZone(options?.timeZone);
-        if (timeZone === "")
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null)
             return "";
         if (!isValidUtc(value))
             return "";
         try {
             const instant = Temporal.Instant.from(value);
-            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-            return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
-                .toString()
-                .padStart(2, "0")}-${zonedDateTime.day.toString().padStart(2, "0")}`;
+            const wallClock = frameWallClock(instant, frame);
+            // Temporal writes the date, so a year outside 0000 to 9999 gets its sign and six digits.
+            return wallClock.toPlainDate().toString();
         }
         catch {
             return "";

package/dist/utc/convert/convertUtcToPlainDateTime.d.ts

@@ -2,6 +2,9 @@
  * Convert a UTC datetime string to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
  *
  * - Converts to the `timeZone` option's zone before extracting the datetime.
+ * - The time is cut to the second: a fraction of a second in `value` is dropped.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it, so the result is always a string `isValidDateTime` accepts.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
@@ -9,13 +12,17 @@
  * @returns plain datetime string in "YYYY-MM-DDTHH:mm:ss" format or "" on invalid input
  *
  * @example convertUtcToPlainDateTime("2024-02-29T00:00:00Z") // "2024-02-29T00:00:00"
- * @example convertUtcToPlainDateTime("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "2024-02-28T19:00:00"
+ * @example convertUtcToPlainDateTime("2024-02-29T00:00:00Z", { timeZone: "Asia/Kolkata" }) // "2024-02-29T05:30:00"
  * @example convertUtcToPlainDateTime("invalid") // ""
+ * @example convertUtcToPlainDateTime("+010000-01-01T00:00:00Z") // "+010000-01-01T00:00:00" (a year past 9999 has a sign and six digits)
+ * @example convertUtcToPlainDateTime("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" }) // "1970-01-01T12:00:00" (a stored offset with seconds)
  */
 export declare function convertUtcToPlainDateTime(value: string, options?: {
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/utc/convert/convertUtcToPlainDateTime.js

@@ -1,12 +1,15 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { Temporal } from "@js-temporal/polyfill";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { Temporal } from "../../internal/temporal.js";
+import { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
  *
  * - Converts to the `timeZone` option's zone before extracting the datetime.
+ * - The time is cut to the second: a fraction of a second in `value` is dropped.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it, so the result is always a string `isValidDateTime` accepts.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
@@ -14,31 +17,27 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @returns plain datetime string in "YYYY-MM-DDTHH:mm:ss" format or "" on invalid input
  *
  * @example convertUtcToPlainDateTime("2024-02-29T00:00:00Z") // "2024-02-29T00:00:00"
- * @example convertUtcToPlainDateTime("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "2024-02-28T19:00:00"
+ * @example convertUtcToPlainDateTime("2024-02-29T00:00:00Z", { timeZone: "Asia/Kolkata" }) // "2024-02-29T05:30:00"
  * @example convertUtcToPlainDateTime("invalid") // ""
+ * @example convertUtcToPlainDateTime("+010000-01-01T00:00:00Z") // "+010000-01-01T00:00:00" (a year past 9999 has a sign and six digits)
+ * @example convertUtcToPlainDateTime("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" }) // "1970-01-01T12:00:00" (a stored offset with seconds)
  */
 export function convertUtcToPlainDateTime(value, options) {
     try {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const timeZone = normalizeTimeZone(options?.timeZone);
-        if (timeZone === "")
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null)
             return "";
         if (!isValidUtc(value))
             return "";
         try {
             const instant = Temporal.Instant.from(value);
-            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-            return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
-                .toString()
-                .padStart(2, "0")}-${zonedDateTime.day
-                .toString()
-                .padStart(2, "0")}T${zonedDateTime.hour
-                .toString()
-                .padStart(2, "0")}:${zonedDateTime.minute
-                .toString()
-                .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+            const wallClock = frameWallClock(instant, frame);
+            // Temporal writes the date-time, so a year outside 0000 to 9999 gets its sign and six
+            // digits. `smallestUnit: "second"` always prints the seconds and cuts off any fraction.
+            return wallClock.toString({ smallestUnit: "second" });
         }
         catch {
             return "";

package/dist/utc/convert/convertUtcToPlainTime.d.ts

@@ -9,13 +9,16 @@
  * @returns plain time string in "HH:mm:ss" format or "" on invalid input
  *
  * @example convertUtcToPlainTime("2024-02-29T00:00:00Z") // "00:00:00"
- * @example convertUtcToPlainTime("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "19:00:00"
+ * @example convertUtcToPlainTime("2024-02-29T00:00:00Z", { timeZone: "Asia/Tokyo" }) // "09:00:00"
  * @example convertUtcToPlainTime("invalid") // ""
+ * @example convertUtcToPlainTime("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export declare function convertUtcToPlainTime(value: string, options?: {
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/utc/convert/convertUtcToPlainTime.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { Temporal } from "@js-temporal/polyfill";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { Temporal } from "../../internal/temporal.js";
+import { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -14,25 +14,26 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @returns plain time string in "HH:mm:ss" format or "" on invalid input
  *
  * @example convertUtcToPlainTime("2024-02-29T00:00:00Z") // "00:00:00"
- * @example convertUtcToPlainTime("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "19:00:00"
+ * @example convertUtcToPlainTime("2024-02-29T00:00:00Z", { timeZone: "Asia/Tokyo" }) // "09:00:00"
  * @example convertUtcToPlainTime("invalid") // ""
+ * @example convertUtcToPlainTime("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export function convertUtcToPlainTime(value, options) {
     try {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const timeZone = normalizeTimeZone(options?.timeZone);
-        if (timeZone === "")
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null)
             return "";
         if (!isValidUtc(value))
             return "";
         try {
             const instant = Temporal.Instant.from(value);
-            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-            return `${zonedDateTime.hour.toString().padStart(2, "0")}:${zonedDateTime.minute
+            const wallClock = frameWallClock(instant, frame);
+            return `${wallClock.hour.toString().padStart(2, "0")}:${wallClock.minute
                 .toString()
-                .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+                .padStart(2, "0")}:${wallClock.second.toString().padStart(2, "0")}`;
         }
         catch {
             return "";

package/dist/utc/convert/convertUtcToUnix.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { resolveUnixEpochUnitOptions, toUnixEpoch, } from "../../internal/unixEpochValue.js";
 import { isValidUtc } from "../validate/index.js";
 /**

package/dist/utc/convert/convertUtcToZoned.d.ts

@@ -4,12 +4,16 @@
  * - Uses Temporal.Instant.from to parse, converts to specified timezone.
  * - Validates both UTC input and timezone.
  * - 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 UTC Instant string
- * @param timeZone IANA name or UTC offset
+ * @param timeZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @returns zoned ISO 8601 string or "" on invalid
  *
- * @example convertUtcToZoned("2024-02-29T00:00:00Z", "America/New_York") // "2024-02-28T19:00:00-05:00[America/New_York]"
+ * @example convertUtcToZoned("2024-02-29T00:00:00Z", "Australia/Sydney") // "2024-02-29T11:00:00+11:00[Australia/Sydney]"
  * @example convertUtcToZoned("invalid", "UTC") // ""
  */
 export declare function convertUtcToZoned(value: string, timeZone: string): string;

package/dist/utc/convert/convertUtcToZoned.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidTimeZone } from "../../zoned/validate/index.js";
 import { isValidUtc } from "../validate/index.js";
 /**
@@ -7,12 +7,16 @@ import { isValidUtc } from "../validate/index.js";
  * - Uses Temporal.Instant.from to parse, converts to specified timezone.
  * - Validates both UTC input and timezone.
  * - 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 UTC Instant string
- * @param timeZone IANA name or UTC offset
+ * @param timeZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @returns zoned ISO 8601 string or "" on invalid
  *
- * @example convertUtcToZoned("2024-02-29T00:00:00Z", "America/New_York") // "2024-02-28T19:00:00-05:00[America/New_York]"
+ * @example convertUtcToZoned("2024-02-29T00:00:00Z", "Australia/Sydney") // "2024-02-29T11:00:00+11:00[Australia/Sydney]"
  * @example convertUtcToZoned("invalid", "UTC") // ""
  */
 export function convertUtcToZoned(value, timeZone) {

package/dist/utc/format/formatCalendarUtc.d.ts

@@ -6,16 +6,17 @@ import type { CalendarOptions } from "../../types/index.js";
 export interface FormatCalendarUtcOptions extends CalendarOptions {
     /**
      * The time zone used for both the calendar-day comparison and the rendered clock time: an IANA
-     * name, a UTC offset, or `"local"` for the system time zone. An unknown zone returns `""`, as
-     * ECMA-402 throws RangeError for it.
+     * name, a UTC offset to the minute (what `isValidTimeZone` accepts), or `"local"` for the system
+     * time zone. An unknown zone returns `""`, as ECMA-402 throws RangeError for it.
      *
      * @defaultValue `"UTC"`
      */
     timeZone?: string;
     /**
      * The length of the time-of-day part, as the `timeStyle` of `Intl.DateTimeFormat`. `"short"`
-     * writes hours and minutes, `"medium"` adds seconds, `"long"` adds the short time zone name
-     * ("EDT") and `"full"` the long one ("Eastern Daylight Time"). Any other value returns `""`.
+     * writes hours and minutes, `"medium"` adds seconds, `"long"` adds the locale's short zone
+     * name ("BST" in en-GB, "GMT+1" in en-US) and `"full"` the long one ("British Summer Time" in
+     * English). Any other value returns `""`.
      *
      * @defaultValue `"short"`
      */
@@ -23,21 +24,25 @@ export interface FormatCalendarUtcOptions extends CalendarOptions {
 }
 /**
  * Format a UTC ISO string as a relative day label plus time-of-day, e.g.
- * "Tomorrow at 2:30 PM" — the UTC counterpart of `formatCalendar`. See that
+ * "tomorrow at 14:30" — the UTC counterpart of `formatCalendar`. See that
  * function's JSDoc for the day-label/threshold/connector design; this
  * variant compares calendar days and renders the clock time in `timeZone`.
  *
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
+ * - 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 value UTC ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options The reference instant, the time zone and the time style
  * @returns the formatted calendar string, or "" on invalid input
  *
- * @example formatCalendarUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", reference: "2026-03-15T13:00:00Z" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarUtc("2026-03-16T18:30:00Z", "en-GB", { timeZone: "Africa/Johannesburg", reference: "2026-03-15T13:00:00Z" }) // "tomorrow at 20:30"
  * @example formatCalendarUtc("2026-03-16T13:30:00Z", "fr-FR", { timeZone: "Europe/Paris", reference: "2026-03-15T12:00:00Z" }) // "demain à 14:30"
- * @example formatCalendarUtc("2026-03-16T18:30:00Z", "en-US", null as never) // ""
+ * @example formatCalendarUtc("2026-03-16T18:30:00Z", "hi-IN", null as never) // ""
  * @example formatCalendarUtc("not-a-date") // ""
  * @example formatCalendarUtc("2024-03-16T18:30:00Z", ["fr-FR", "en-US"], { reference: "2024-03-15T13:00:00Z" }) // "demain à 18:30"
  */