@northguild/gmt 1.18.0 → 1.19.0

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 { 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")
@@ -16,23 +18,24 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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("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")
@@ -11,11 +14,15 @@
  * @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("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 { 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")
@@ -16,29 +19,25 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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("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

@@ -11,11 +11,14 @@
  * @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("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 { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -16,23 +16,24 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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("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/convertUtcToZoned.d.ts

@@ -4,9 +4,13 @@
  * - 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]"

package/dist/utc/convert/convertUtcToZoned.js

@@ -7,9 +7,13 @@ 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]"

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

@@ -6,8 +6,8 @@ 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"`
      */
@@ -29,6 +29,10 @@ export interface FormatCalendarUtcOptions extends CalendarOptions {
  *
  * - `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)

package/dist/utc/format/formatCalendarUtc.js

@@ -4,6 +4,7 @@ import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { toInstantFromUtc, toReferenceInstantFromUtc, } from "../../internal/toInstantFromUtc.js";
 import { isValidUtc } from "../validate/index.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * 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
@@ -12,6 +13,10 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  *
  * - `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)
@@ -28,7 +33,7 @@ export function formatCalendarUtc(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: undefined is defaults (the parameter default); anything else that is
         // not an object, including null, is a TypeError.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidUtc(value))
             return "";

package/dist/utc/format/{formatHttp.d.ts → formatHttpDate.d.ts}

@@ -1,6 +1,6 @@
 /**
- * Format a UTC ISO 8601 datetime string as an RFC 9110 IMF-fixdate — the
- * fixed grammar HTTP headers like `Last-Modified`/`Date`/`Expires` require.
+ * Format a UTC ISO 8601 datetime string as an HTTP header date — the RFC 9110
+ * IMF-fixdate that headers like `Last-Modified`/`Date`/`Expires` require.
  *
  * - **Fixed grammar, not a display format.** RFC 9110 mandates English
  *   weekday/month abbreviations and a literal `GMT` suffix regardless of
@@ -19,10 +19,10 @@
  * @param value UTC ISO 8601 datetime string (e.g. "2024-03-15T14:30:00Z")
  * @returns RFC 9110 IMF-fixdate string, or "" on invalid input or a year outside 0000–9999
  *
- * @example formatHttp("2024-03-15T14:30:00Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
- * @example formatHttp("2024-03-15T14:30:00.500Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
- * @example formatHttp("-000001-06-15T12:00:00Z") // ""
+ * @example formatHttpDate("2024-03-15T14:30:00Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
+ * @example formatHttpDate("2024-03-15T14:30:00.500Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
+ * @example formatHttpDate("-000001-06-15T12:00:00Z") // ""
  * @example Temporal.Instant.from("-000001-06-15T12:00:00Z").toString() // "-000001-06-15T12:00:00Z"
- * @example formatHttp("invalid") // ""
+ * @example formatHttpDate("invalid") // ""
  */
-export declare function formatHttp(value: string): string;
+export declare function formatHttpDate(value: string): string;

package/dist/utc/format/{formatHttp.js → formatHttpDate.js}

@@ -2,8 +2,8 @@ import { Temporal } from "@js-temporal/polyfill";
 import { englishDateTimeStem } from "../../internal/englishCalendarNames.js";
 import { isValidUtc } from "../validate/index.js";
 /**
- * Format a UTC ISO 8601 datetime string as an RFC 9110 IMF-fixdate — the
- * fixed grammar HTTP headers like `Last-Modified`/`Date`/`Expires` require.
+ * Format a UTC ISO 8601 datetime string as an HTTP header date — the RFC 9110
+ * IMF-fixdate that headers like `Last-Modified`/`Date`/`Expires` require.
  *
  * - **Fixed grammar, not a display format.** RFC 9110 mandates English
  *   weekday/month abbreviations and a literal `GMT` suffix regardless of
@@ -22,13 +22,13 @@ import { isValidUtc } from "../validate/index.js";
  * @param value UTC ISO 8601 datetime string (e.g. "2024-03-15T14:30:00Z")
  * @returns RFC 9110 IMF-fixdate string, or "" on invalid input or a year outside 0000–9999
  *
- * @example formatHttp("2024-03-15T14:30:00Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
- * @example formatHttp("2024-03-15T14:30:00.500Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
- * @example formatHttp("-000001-06-15T12:00:00Z") // ""
+ * @example formatHttpDate("2024-03-15T14:30:00Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
+ * @example formatHttpDate("2024-03-15T14:30:00.500Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
+ * @example formatHttpDate("-000001-06-15T12:00:00Z") // ""
  * @example Temporal.Instant.from("-000001-06-15T12:00:00Z").toString() // "-000001-06-15T12:00:00Z"
- * @example formatHttp("invalid") // ""
+ * @example formatHttpDate("invalid") // ""
  */
-export function formatHttp(value) {
+export function formatHttpDate(value) {
     if (!isValidUtc(value))
         return "";
     try {

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

@@ -20,9 +20,10 @@ export interface FormatRelativeUtcOptions extends RelativeTimeFormatOptions {
      */
     reference?: string;
     /**
-     * The time zone that anchors a calendar unit (week, month or year): an IANA name, a UTC offset,
-     * or `"local"` for the system time zone. An unknown zone returns `""` whatever the unit, as
-     * ECMA-402 throws RangeError for it.
+     * The time zone that anchors a calendar unit (week, month or year): 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
+     * `""` whatever the unit.
      *
      * @defaultValue `"UTC"`
      */
@@ -39,6 +40,12 @@ export interface FormatRelativeUtcOptions extends RelativeTimeFormatOptions {
  *   other value returns `""`.
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
+ * - **Limit at an offset with seconds.** A month or a year is measured from `reference`, placed in
+ *   the offset's whole-minute zone and moved by its seconds, and the moved instant must be inside
+ *   Temporal's range. So when one is measured and `reference` is within the offset's seconds (under
+ *   a minute) of the last instant Temporal supports (`+275760-09-13T00:00:00Z`) for an offset east
+ *   of UTC, or of the first (`-271821-04-20T00:00:00Z`) for one west, this returns `""`. An offset
+ *   to the minute has no such limit.
  *
  * @param value UTC ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
@@ -51,5 +58,6 @@ export interface FormatRelativeUtcOptions extends RelativeTimeFormatOptions {
  * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", null as never) // ""
  * @example formatRelativeUtc("not-a-date") // ""
  * @example formatRelativeUtc("2024-03-15T11:30:00Z", ["fr-FR", "en-US"], { reference: "2024-03-15T12:00:00Z" }) // "il y a 30 minutes"
+ * @example formatRelativeUtc("1970-01-03T12:00:00Z", "en-US", { reference: "1970-01-01T12:00:00Z", timeZone: "-00:44:30" }) // "in 2 days" (a stored offset with seconds)
  */
 export declare function formatRelativeUtc(value: string, locale?: string | string[], options?: FormatRelativeUtcOptions): string;

package/dist/utc/format/formatRelativeUtc.js

@@ -1,9 +1,10 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { frameZoned, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { toInstantFromUtc, toReferenceInstantFromUtc, } from "../../internal/toInstantFromUtc.js";
 import { durationTotal } from "../../internal/zonedWallClockDifference.js";
 import { isValidUtc } from "../validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Format the relative time between a UTC ISO string and a reference instant.
  *
@@ -15,6 +16,12 @@ import { isValidUtc } from "../validate/index.js";
  *   other value returns `""`.
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
+ * - **Limit at an offset with seconds.** A month or a year is measured from `reference`, placed in
+ *   the offset's whole-minute zone and moved by its seconds, and the moved instant must be inside
+ *   Temporal's range. So when one is measured and `reference` is within the offset's seconds (under
+ *   a minute) of the last instant Temporal supports (`+275760-09-13T00:00:00Z`) for an offset east
+ *   of UTC, or of the first (`-271821-04-20T00:00:00Z`) for one west, this returns `""`. An offset
+ *   to the minute has no such limit.
  *
  * @param value UTC ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
@@ -27,17 +34,18 @@ import { isValidUtc } from "../validate/index.js";
  * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", null as never) // ""
  * @example formatRelativeUtc("not-a-date") // ""
  * @example formatRelativeUtc("2024-03-15T11:30:00Z", ["fr-FR", "en-US"], { reference: "2024-03-15T12:00:00Z" }) // "il y a 30 minutes"
+ * @example formatRelativeUtc("1970-01-03T12:00:00Z", "en-US", { reference: "1970-01-01T12:00:00Z", timeZone: "-00:44:30" }) // "in 2 days" (a stored offset with seconds)
  */
 export function formatRelativeUtc(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: undefined is defaults (the parameter default); anything else that is
         // not an object, including null, is a TypeError.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidUtc(value))
             return "";
-        const tz = normalizeTimeZone(options.timeZone);
-        if (!tz)
+        const frame = normalizeZoneFrame(options.timeZone);
+        if (frame === null)
             return "";
         // Each option is read once (GetOption).
         const referenceOption = options.reference;
@@ -52,7 +60,7 @@ export function formatRelativeUtc(value, locale, options = {}) {
         try {
             const diff = target.since(reference);
             // Only a calendrical unit (month, year) reads the anchor, so the zone is applied lazily.
-            return formatRelativeDuration(diff, locale, options, (unit) => durationTotal(diff, unit, reference.toZonedDateTimeISO(tz)));
+            return formatRelativeDuration(diff, locale, options, (unit) => durationTotal(diff, unit, frameZoned(reference, frame)));
         }
         catch {
             return "";

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

@@ -9,8 +9,9 @@
  */
 export interface FormatUtcOptions extends Intl.DateTimeFormatOptions {
     /**
-     * The time zone the value is rendered in: an IANA name, a UTC offset, or `"local"` for the system
-     * time zone. An unknown zone returns `""`, as ECMA-402 throws RangeError for it.
+     * The time zone the value is rendered in: an IANA 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"`
      */
@@ -35,6 +36,10 @@ export interface FormatUtcOptions extends Intl.DateTimeFormatOptions {
  *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
  *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
  * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject 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)

package/dist/utc/format/formatUtc.js

@@ -17,6 +17,10 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
  *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
  * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject 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)

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

@@ -1,4 +1,4 @@
 export * from "./formatCalendarUtc.js";
-export * from "./formatHttp.js";
+export * from "./formatHttpDate.js";
 export * from "./formatRelativeUtc.js";
 export * from "./formatUtc.js";

package/dist/utc/format/index.js

@@ -1,4 +1,4 @@
 export * from "./formatCalendarUtc.js";
-export * from "./formatHttp.js";
+export * from "./formatHttpDate.js";
 export * from "./formatRelativeUtc.js";
 export * from "./formatUtc.js";

package/dist/utc/get/getUtcDay.d.ts

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current day string (zero-padded to 2 digits) or "" on failure
+ * @returns current day string (zero-padded to 2 digits)
  *
  * @example getUtcDay() // "29"
- * @example getUtcDay() // "" (on failure)
  */
 export declare function getUtcDay(): string;

package/dist/utc/get/getUtcDay.js

@@ -4,21 +4,14 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current day string (zero-padded to 2 digits) or "" on failure
+ * @returns current day string (zero-padded to 2 digits)
  *
  * @example getUtcDay() // "29"
- * @example getUtcDay() // "" (on failure)
  */
 export function getUtcDay() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .day.toString()
-            .padStart(2, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .day.toString()
+        .padStart(2, "0");
 }

package/dist/utc/get/getUtcHour.d.ts

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current hour string (zero-padded to 2 digits) or "" on failure
+ * @returns current hour string (zero-padded to 2 digits)
  *
  * @example getUtcHour() // "00"
- * @example getUtcHour() // "" (on failure)
  */
 export declare function getUtcHour(): string;

package/dist/utc/get/getUtcHour.js

@@ -4,21 +4,14 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current hour string (zero-padded to 2 digits) or "" on failure
+ * @returns current hour string (zero-padded to 2 digits)
  *
  * @example getUtcHour() // "00"
- * @example getUtcHour() // "" (on failure)
  */
 export function getUtcHour() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .hour.toString()
-            .padStart(2, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .hour.toString()
+        .padStart(2, "0");
 }

package/dist/utc/get/getUtcMicrosecond.d.ts

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current microsecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current microsecond string (zero-padded to 3 digits)
  *
  * @example getUtcMicrosecond() // "456"
- * @example getUtcMicrosecond() // "" (on failure)
  */
 export declare function getUtcMicrosecond(): string;

package/dist/utc/get/getUtcMicrosecond.js

@@ -4,20 +4,13 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current microsecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current microsecond string (zero-padded to 3 digits)
  *
  * @example getUtcMicrosecond() // "456"
- * @example getUtcMicrosecond() // "" (on failure)
  */
 export function getUtcMicrosecond() {
-    try {
-        return (Temporal.Now.instant().toZonedDateTimeISO("UTC").microsecond ?? 0)
-            .toString()
-            .padStart(3, "0");
-    }
-    catch {
-        return "";
-    }
+    return (Temporal.Now.instant().toZonedDateTimeISO("UTC").microsecond ?? 0)
+        .toString()
+        .padStart(3, "0");
 }

package/dist/utc/get/getUtcMillisecond.d.ts

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current millisecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current millisecond string (zero-padded to 3 digits)
  *
  * @example getUtcMillisecond() // "123"
- * @example getUtcMillisecond() // "" (on failure)
  */
 export declare function getUtcMillisecond(): string;