@northguild/gmt 1.17.0 → 1.19.0

package/dist/utc/format/formatRelativeUtc.js

@@ -1,28 +1,31 @@
 // 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.
  *
- * - Auto-picks the display unit based on the distance, unless `largestUnit` forces one: second
- *   under a minute, minute under an hour, hour under a day, then `formatRelativeDate`'s thresholds —
- *   day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads
- *   "3 years ago".
+ * - Picks the display unit from the distance, using `formatRelativeDate`'s day thresholds past a
+ *   day, so a 3-year distance reads "3 years ago".
  * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
  *   Pass `largestUnit: "day"` to keep a day count.
- * - `roundingMethod` controls how the distance rounds to the display unit.
- * - `timeZone` anchors a calendar unit (week, month or year, auto-picked or forced). Omitted, it is
- *   `"UTC"`; pass `"local"` for the system time zone. An unknown zone returns `""` whatever the unit
- *   (ECMA-402 throws RangeError for it).
+ * - `largestUnit` is one of the seven units from `"second"` to `"year"`, singular or plural. Any
+ *   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)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference, timeZone }
+ * @param options The reference instant, the display unit, rounding, wording and time zone
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", { reference: "2026-04-15T14:30:45Z" }) // "3 months ago"
@@ -31,30 +34,33 @@ 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 "";
-        if (options.reference !== undefined && !isValidUtc(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (referenceOption !== undefined && !isValidUtc(referenceOption))
             return "";
         const target = toInstantFromUtc(value);
         if (target === null)
             return "";
-        const reference = toReferenceInstantFromUtc(options.reference);
+        const reference = toReferenceInstantFromUtc(referenceOption);
         if (reference === null)
             return "";
         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

@@ -1,42 +1,49 @@
 /**
  * Options for `formatUtc`. Extends `Intl.DateTimeFormatOptions`; only the
- * added/overridden members are listed below. All `Intl.DateTimeFormatOptions`
+ * added/overridden members are declared here. All `Intl.DateTimeFormatOptions`
  * (`dateStyle`, `timeStyle`, etc.) apply to the time-of-day portion.
  *
- * @remarks Members:
- *
- * | Member | Type | Default | Description |
- * | --- | --- | --- | --- |
- * | `timeZone` | `string` | `"UTC"` | IANA zone for rendering; omitted is UTC, `"local"` is the system zone, and an unknown zone makes `formatUtc` return `""`. |
- * | `includeTimeZoneName` | `boolean` | `false` | Appends the localized zone name (style via `Intl`) when true. |
- *
  * @example
  * import { FormatUtcOptions } from "@northguild/gmt/utc";
  * const opts: FormatUtcOptions = { includeTimeZoneName: true };
  */
 export interface FormatUtcOptions extends Intl.DateTimeFormatOptions {
+    /**
+     * 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"`
+     */
     timeZone?: string;
+    /**
+     * Whether the localized time zone name is appended. When true the value is formatted as Temporal's
+     * ECMA-402 ZonedDateTime format does, which adds a short zone name to the defaults; when false, as
+     * the PlainDateTime format does, and `timeZoneName` is ignored.
+     *
+     * @defaultValue `false`
+     */
     includeTimeZoneName?: boolean;
 }
 /**
  * Format a UTC ISO string as a localized date/time string.
  *
  * - Returns `""` if the input is not a valid UTC string.
- * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
- * - `includeTimeZoneName` appends the localized timezone name when true.
- * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
- *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
- *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
- *   and `era` alone still gets the date and time defaults.
+ * - The requested fields and style widths are kept, and `era` alone still gets the date and time
+ *   defaults.
  * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
  *   the japanese calendar and `month: "long"` gave `"R6/2"`), a `long`/`full` `timeStyle` replaced
  *   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)
- * @param options optional: { timeZone, includeTimeZoneName }
+ * @param options The time zone, the zone-name switch and any `Intl.DateTimeFormatOptions`
  * @returns the formatted date/time string, or "" on invalid input
  *
  * @example formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"

package/dist/utc/format/formatUtc.js

@@ -4,25 +4,27 @@ import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { toInstantFromUtc } from "../../internal/toInstantFromUtc.js";
 import { isValidUtc } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Format a UTC ISO string as a localized date/time string.
  *
  * - Returns `""` if the input is not a valid UTC string.
- * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
- * - `includeTimeZoneName` appends the localized timezone name when true.
- * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
- *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
- *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
- *   and `era` alone still gets the date and time defaults.
+ * - The requested fields and style widths are kept, and `era` alone still gets the date and time
+ *   defaults.
  * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
  *   the japanese calendar and `month: "long"` gave `"R6/2"`), a `long`/`full` `timeStyle` replaced
  *   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)
- * @param options optional: { timeZone, includeTimeZoneName }
+ * @param options The time zone, the zone-name switch and any `Intl.DateTimeFormatOptions`
  * @returns the formatted date/time string, or "" on invalid input
  *
  * @example formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"
@@ -45,7 +47,9 @@ export function formatUtc(value, locale, options) {
             return "";
         if (!isValidUtc(value))
             return "";
-        const { timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
+        // Each option is read once (GetOption), inherited ones included.
+        const includeTimeZoneName = optionOrDefault(options?.includeTimeZoneName, false);
+        const { timeZone, ...intlOptions } = readDateTimeFormatOptions(options);
         const instant = toInstantFromUtc(value);
         if (instant === null)
             return "";

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;

package/dist/utc/get/getUtcMillisecond.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 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 function getUtcMillisecond() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .millisecond.toString()
-            .padStart(3, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .millisecond.toString()
+        .padStart(3, "0");
 }

package/dist/utc/get/getUtcMinute.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 minute string (zero-padded to 2 digits) or "" on failure
+ * @returns current minute string (zero-padded to 2 digits)
  *
  * @example getUtcMinute() // "30"
- * @example getUtcMinute() // "" (on failure)
  */
 export declare function getUtcMinute(): string;

package/dist/utc/get/getUtcMinute.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 minute string (zero-padded to 2 digits) or "" on failure
+ * @returns current minute string (zero-padded to 2 digits)
  *
  * @example getUtcMinute() // "30"
- * @example getUtcMinute() // "" (on failure)
  */
 export function getUtcMinute() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .minute.toString()
-            .padStart(2, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .minute.toString()
+        .padStart(2, "0");
 }

package/dist/utc/get/getUtcMonth.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 month string (zero-padded to 2 digits) or "" on failure
+ * @returns current month string (zero-padded to 2 digits)
  *
  * @example getUtcMonth() // "02"
- * @example getUtcMonth() // "" (on failure)
  */
 export declare function getUtcMonth(): string;

package/dist/utc/get/getUtcMonth.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 month string (zero-padded to 2 digits) or "" on failure
+ * @returns current month string (zero-padded to 2 digits)
  *
  * @example getUtcMonth() // "02"
- * @example getUtcMonth() // "" (on failure)
  */
 export function getUtcMonth() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .month.toString()
-            .padStart(2, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .month.toString()
+        .padStart(2, "0");
 }

package/dist/utc/get/getUtcNanosecond.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 nanosecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current nanosecond string (zero-padded to 3 digits)
  *
  * @example getUtcNanosecond() // "789"
- * @example getUtcNanosecond() // "" (on failure)
  */
 export declare function getUtcNanosecond(): string;

package/dist/utc/get/getUtcNanosecond.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 nanosecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current nanosecond string (zero-padded to 3 digits)
  *
  * @example getUtcNanosecond() // "789"
- * @example getUtcNanosecond() // "" (on failure)
  */
 export function getUtcNanosecond() {
-    try {
-        return (Temporal.Now.instant().toZonedDateTimeISO("UTC").nanosecond ?? 0)
-            .toString()
-            .padStart(3, "0");
-    }
-    catch {
-        return "";
-    }
+    return (Temporal.Now.instant().toZonedDateTimeISO("UTC").nanosecond ?? 0)
+        .toString()
+        .padStart(3, "0");
 }

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

@@ -2,11 +2,9 @@
  * Return the current UTC instant as an ISO Instant string.
  *
  * - Uses Temporal.Now.instant() to get current UTC time.
- * - Returns "" on failure.
  *
- * @returns ISO Instant string (e.g. "2024-02-29T00:00:00Z") or "" on failure
+ * @returns ISO Instant string (e.g. "2024-02-29T00:00:00Z")
  *
  * @example getUtcNow() // "2024-02-29T00:00:00Z"
- * @example getUtcNow() // "" (on failure)
  */
 export declare function getUtcNow(): string;

package/dist/utc/get/getUtcNow.js

@@ -3,18 +3,11 @@ import { Temporal } from "@js-temporal/polyfill";
  * Return the current UTC instant as an ISO Instant string.
  *
  * - Uses Temporal.Now.instant() to get current UTC time.
- * - Returns "" on failure.
  *
- * @returns ISO Instant string (e.g. "2024-02-29T00:00:00Z") or "" on failure
+ * @returns ISO Instant string (e.g. "2024-02-29T00:00:00Z")
  *
  * @example getUtcNow() // "2024-02-29T00:00:00Z"
- * @example getUtcNow() // "" (on failure)
  */
 export function getUtcNow() {
-    try {
-        return Temporal.Now.instant().toString();
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant().toString();
 }

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

@@ -8,6 +8,8 @@ export type { UtcNowUnit };
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
  * - Returns "" on invalid unit or failure.
+ * - 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 unit unit to extract from current utc instant
  * @returns string representation of the requested unit or "" on invalid

package/dist/utc/get/getUtcNowUnit.js

@@ -13,6 +13,8 @@ function isValidUtcNowUnit(unit) {
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
  * - Returns "" on invalid unit or failure.
+ * - 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 unit unit to extract from current utc instant
  * @returns string representation of the requested unit or "" on invalid

package/dist/utc/get/getUtcSecond.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 second string (zero-padded to 2 digits) or "" on failure
+ * @returns current second string (zero-padded to 2 digits)
  *
  * @example getUtcSecond() // "45"
- * @example getUtcSecond() // "" (on failure)
  */
 export declare function getUtcSecond(): string;

package/dist/utc/get/getUtcSecond.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 second string (zero-padded to 2 digits) or "" on failure
+ * @returns current second string (zero-padded to 2 digits)
  *
  * @example getUtcSecond() // "45"
- * @example getUtcSecond() // "" (on failure)
  */
 export function getUtcSecond() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .second.toString()
-            .padStart(2, "0");
-    }
-    catch {
-        return "";
-    }
+    return Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .second.toString()
+        .padStart(2, "0");
 }

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

@@ -3,11 +3,11 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 4 digits.
- * - Returns "" on failure.
+ * - 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.
  *
- * @returns current year string (zero-padded to 4 digits) or "" on failure
+ * @returns current year string (zero-padded to 4 digits)
  *
  * @example getUtcYear() // "2024"
- * @example getUtcYear() // "" (on failure)
  */
 export declare function getUtcYear(): string;