@northguild/gmt 1.17.0 → 1.19.0

package/dist/utc/parse/parseHourFromUtc.js

@@ -1,15 +1,13 @@
-import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { utcWallClock } from "../../internal/utcWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the hour (0-23) from a UTC datetime string.
  *
  * - Returns zero-padded string for hour.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Hour (00-23) or "" on invalid input
  *
  * @example parseHourFromUtc("2024-03-17T14:30:45Z") // "14"
@@ -21,7 +19,7 @@ export function parseHourFromUtc(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const dateTime = utcZonedDateTime(value, options);
+        const dateTime = utcWallClock(value, options);
         return dateTime === null ? "" : dateTime.hour.toString().padStart(2, "0");
     }
     catch {

package/dist/utc/parse/{parseHttp.d.ts → parseHttpDate.d.ts}

@@ -1,9 +1,9 @@
 /**
- * Parse an RFC 9110 HTTP-date — the fixed grammar HTTP headers like
- * `Last-Modified`/`Date`/`Expires` use — into a UTC ISO 8601 datetime string.
+ * Parse an HTTP header date — the RFC 9110 HTTP-date that headers like
+ * `Last-Modified`/`Date`/`Expires` carry — into a UTC ISO 8601 datetime string.
  *
  * - **Decoding, not display.** Accepts English weekday/month names only, per
- *   the fixed grammar (see `formatHttp`'s JSDoc and roadmap Decision 1).
+ *   the fixed grammar (see `formatHttpDate`'s JSDoc).
  * - **All three HTTP-date formats**, as RFC 9110 §5.6.7 requires ("A
  *   recipient that parses a timestamp value in an HTTP field MUST accept all
  *   three"): IMF-fixdate (`Sun, 06 Nov 1994 08:49:37 GMT`), the obsolete
@@ -36,14 +36,14 @@
  * @param value RFC 9110 HTTP-date string (e.g. "Fri, 15 Mar 2024 14:30:00 GMT")
  * @returns UTC ISO 8601 datetime string, or "" on invalid input
  *
- * @example parseHttp("Fri, 15 Mar 2024 14:30:00 GMT") // "2024-03-15T14:30:00Z"
- * @example parseHttp("Sunday, 06-Nov-94 08:49:37 GMT") // "1994-11-06T08:49:37Z" (rfc850-date)
- * @example parseHttp("Sun Nov  6 08:49:37 1994") // "1994-11-06T08:49:37Z" (asctime-date)
- * @example parseHttp("Fri, 15 Mar 2024 14:30:00 -0400") // "" (not an HTTP-date)
- * @example parseHttp("Sat, 15 Mar 2024 14:30:00 GMT") // "" (15 Mar 2024 was a Friday)
- * @example parseHttp("Mon Nov  6 08:49:37 1994") // "" (asctime-date; 6 Nov 1994 was a Sunday)
+ * @example parseHttpDate("Fri, 15 Mar 2024 14:30:00 GMT") // "2024-03-15T14:30:00Z"
+ * @example parseHttpDate("Sunday, 06-Nov-94 08:49:37 GMT") // "1994-11-06T08:49:37Z" (rfc850-date)
+ * @example parseHttpDate("Sun Nov  6 08:49:37 1994") // "1994-11-06T08:49:37Z" (asctime-date)
+ * @example parseHttpDate("Fri, 15 Mar 2024 14:30:00 -0400") // "" (not an HTTP-date)
+ * @example parseHttpDate("Sat, 15 Mar 2024 14:30:00 GMT") // "" (15 Mar 2024 was a Friday)
+ * @example parseHttpDate("Mon Nov  6 08:49:37 1994") // "" (asctime-date; 6 Nov 1994 was a Sunday)
  * @example convertZonedToUtc(parseRfc2822("15 Mar 2024 14:30:00 GMT")) // "2024-03-15T14:30:00Z" — the day name removed
- * @example parseHttp("Sat, 31 Feb 2024 14:30:00 GMT") // "" (impossible date)
- * @example parseHttp("not a date") // ""
+ * @example parseHttpDate("Sat, 31 Feb 2024 14:30:00 GMT") // "" (impossible date)
+ * @example parseHttpDate("not a date") // ""
  */
-export declare function parseHttp(value: string): string;
+export declare function parseHttpDate(value: string): string;

package/dist/utc/parse/{parseHttp.js → parseHttpDate.js}

@@ -3,11 +3,11 @@ import { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES } from "../../internal/index
 import { readObsoleteHttpDate, } from "../../internal/httpDateFields.js";
 import { httpDate } from "../../regex/index.js";
 /**
- * Parse an RFC 9110 HTTP-date — the fixed grammar HTTP headers like
- * `Last-Modified`/`Date`/`Expires` use — into a UTC ISO 8601 datetime string.
+ * Parse an HTTP header date — the RFC 9110 HTTP-date that headers like
+ * `Last-Modified`/`Date`/`Expires` carry — into a UTC ISO 8601 datetime string.
  *
  * - **Decoding, not display.** Accepts English weekday/month names only, per
- *   the fixed grammar (see `formatHttp`'s JSDoc and roadmap Decision 1).
+ *   the fixed grammar (see `formatHttpDate`'s JSDoc).
  * - **All three HTTP-date formats**, as RFC 9110 §5.6.7 requires ("A
  *   recipient that parses a timestamp value in an HTTP field MUST accept all
  *   three"): IMF-fixdate (`Sun, 06 Nov 1994 08:49:37 GMT`), the obsolete
@@ -40,17 +40,17 @@ import { httpDate } from "../../regex/index.js";
  * @param value RFC 9110 HTTP-date string (e.g. "Fri, 15 Mar 2024 14:30:00 GMT")
  * @returns UTC ISO 8601 datetime string, or "" on invalid input
  *
- * @example parseHttp("Fri, 15 Mar 2024 14:30:00 GMT") // "2024-03-15T14:30:00Z"
- * @example parseHttp("Sunday, 06-Nov-94 08:49:37 GMT") // "1994-11-06T08:49:37Z" (rfc850-date)
- * @example parseHttp("Sun Nov  6 08:49:37 1994") // "1994-11-06T08:49:37Z" (asctime-date)
- * @example parseHttp("Fri, 15 Mar 2024 14:30:00 -0400") // "" (not an HTTP-date)
- * @example parseHttp("Sat, 15 Mar 2024 14:30:00 GMT") // "" (15 Mar 2024 was a Friday)
- * @example parseHttp("Mon Nov  6 08:49:37 1994") // "" (asctime-date; 6 Nov 1994 was a Sunday)
+ * @example parseHttpDate("Fri, 15 Mar 2024 14:30:00 GMT") // "2024-03-15T14:30:00Z"
+ * @example parseHttpDate("Sunday, 06-Nov-94 08:49:37 GMT") // "1994-11-06T08:49:37Z" (rfc850-date)
+ * @example parseHttpDate("Sun Nov  6 08:49:37 1994") // "1994-11-06T08:49:37Z" (asctime-date)
+ * @example parseHttpDate("Fri, 15 Mar 2024 14:30:00 -0400") // "" (not an HTTP-date)
+ * @example parseHttpDate("Sat, 15 Mar 2024 14:30:00 GMT") // "" (15 Mar 2024 was a Friday)
+ * @example parseHttpDate("Mon Nov  6 08:49:37 1994") // "" (asctime-date; 6 Nov 1994 was a Sunday)
  * @example convertZonedToUtc(parseRfc2822("15 Mar 2024 14:30:00 GMT")) // "2024-03-15T14:30:00Z" — the day name removed
- * @example parseHttp("Sat, 31 Feb 2024 14:30:00 GMT") // "" (impossible date)
- * @example parseHttp("not a date") // ""
+ * @example parseHttpDate("Sat, 31 Feb 2024 14:30:00 GMT") // "" (impossible date)
+ * @example parseHttpDate("not a date") // ""
  */
-export function parseHttp(value) {
+export function parseHttpDate(value) {
     if (typeof value !== "string")
         return "";
     try {

package/dist/utc/parse/parseMicrosecondFromUtc.d.ts

@@ -2,12 +2,10 @@
  * Return the microsecond (0-999) from a UTC datetime string.
  *
  * - Returns zero-padded string for microsecond.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45.123Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Microsecond (000-999) or "" on invalid input
  *
  * @example parseMicrosecondFromUtc("2024-03-17T14:30:45.123Z") // "000"
@@ -16,5 +14,13 @@
  * @example parseMicrosecondFromUtc("invalid") // ""
  */
 export declare function parseMicrosecondFromUtc(value: string, options?: {
+    /**
+     * 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"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseMicrosecondFromUtc.js

@@ -1,15 +1,13 @@
-import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { utcWallClock } from "../../internal/utcWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the microsecond (0-999) from a UTC datetime string.
  *
  * - Returns zero-padded string for microsecond.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45.123Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Microsecond (000-999) or "" on invalid input
  *
  * @example parseMicrosecondFromUtc("2024-03-17T14:30:45.123Z") // "000"
@@ -22,7 +20,7 @@ export function parseMicrosecondFromUtc(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const dateTime = utcZonedDateTime(value, options);
+        const dateTime = utcWallClock(value, options);
         return dateTime === null
             ? ""
             : dateTime.microsecond.toString().padStart(3, "0");

package/dist/utc/parse/parseMillisecondFromUtc.d.ts

@@ -2,12 +2,10 @@
  * Return the millisecond (0-999) from a UTC datetime string.
  *
  * - Returns zero-padded string for millisecond.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45.123Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Millisecond (000-999) or "" on invalid input
  *
  * @example parseMillisecondFromUtc("2024-03-17T14:30:45.123Z") // "123"
@@ -15,5 +13,13 @@
  * @example parseMillisecondFromUtc("invalid") // ""
  */
 export declare function parseMillisecondFromUtc(value: string, options?: {
+    /**
+     * 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"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseMillisecondFromUtc.js

@@ -1,15 +1,13 @@
-import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { utcWallClock } from "../../internal/utcWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the millisecond (0-999) from a UTC datetime string.
  *
  * - Returns zero-padded string for millisecond.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45.123Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Millisecond (000-999) or "" on invalid input
  *
  * @example parseMillisecondFromUtc("2024-03-17T14:30:45.123Z") // "123"
@@ -21,7 +19,7 @@ export function parseMillisecondFromUtc(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const dateTime = utcZonedDateTime(value, options);
+        const dateTime = utcWallClock(value, options);
         return dateTime === null
             ? ""
             : dateTime.millisecond.toString().padStart(3, "0");

package/dist/utc/parse/parseMinuteFromUtc.d.ts

@@ -2,12 +2,10 @@
  * Return the minute (0-59) from a UTC datetime string.
  *
  * - Returns zero-padded string for minute.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Minute (00-59) or "" on invalid input
  *
  * @example parseMinuteFromUtc("2024-03-17T14:30:45Z") // "30"
@@ -15,5 +13,13 @@
  * @example parseMinuteFromUtc("invalid") // ""
  */
 export declare function parseMinuteFromUtc(value: string, options?: {
+    /**
+     * 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"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseMinuteFromUtc.js

@@ -1,15 +1,13 @@
-import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { utcWallClock } from "../../internal/utcWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the minute (0-59) from a UTC datetime string.
  *
  * - Returns zero-padded string for minute.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Minute (00-59) or "" on invalid input
  *
  * @example parseMinuteFromUtc("2024-03-17T14:30:45Z") // "30"
@@ -21,7 +19,7 @@ export function parseMinuteFromUtc(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const dateTime = utcZonedDateTime(value, options);
+        const dateTime = utcWallClock(value, options);
         return dateTime === null ? "" : dateTime.minute.toString().padStart(2, "0");
     }
     catch {

package/dist/utc/parse/parseMonthFromUtc.d.ts

@@ -2,12 +2,10 @@
  * Return the month (1-12) from a UTC datetime string.
  *
  * - Returns zero-padded string for month.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Month (01-12) or "" on invalid input
  *
  * @example parseMonthFromUtc("2024-03-17T14:30:45Z") // "03"
@@ -15,5 +13,13 @@
  * @example parseMonthFromUtc("invalid") // ""
  */
 export declare function parseMonthFromUtc(value: string, options?: {
+    /**
+     * 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"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseMonthFromUtc.js

@@ -1,15 +1,13 @@
-import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { utcWallClock } from "../../internal/utcWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the month (1-12) from a UTC datetime string.
  *
  * - Returns zero-padded string for month.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Month (01-12) or "" on invalid input
  *
  * @example parseMonthFromUtc("2024-03-17T14:30:45Z") // "03"
@@ -21,7 +19,7 @@ export function parseMonthFromUtc(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const dateTime = utcZonedDateTime(value, options);
+        const dateTime = utcWallClock(value, options);
         return dateTime === null ? "" : dateTime.month.toString().padStart(2, "0");
     }
     catch {

package/dist/utc/parse/parseNanosecondFromUtc.d.ts

@@ -2,12 +2,10 @@
  * Return the nanosecond (0-999) from a UTC datetime string.
  *
  * - Returns zero-padded string for nanosecond.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45.123Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Nanosecond (000-999) or "" on invalid input
  *
  * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123Z") // "000"
@@ -16,5 +14,13 @@
  * @example parseNanosecondFromUtc("invalid") // ""
  */
 export declare function parseNanosecondFromUtc(value: string, options?: {
+    /**
+     * 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"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseNanosecondFromUtc.js

@@ -1,15 +1,13 @@
-import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { utcWallClock } from "../../internal/utcWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the nanosecond (0-999) from a UTC datetime string.
  *
  * - Returns zero-padded string for nanosecond.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45.123Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Nanosecond (000-999) or "" on invalid input
  *
  * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123Z") // "000"
@@ -22,7 +20,7 @@ export function parseNanosecondFromUtc(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const dateTime = utcZonedDateTime(value, options);
+        const dateTime = utcWallClock(value, options);
         return dateTime === null
             ? ""
             : dateTime.nanosecond.toString().padStart(3, "0");

package/dist/utc/parse/parseSecondFromUtc.d.ts

@@ -2,12 +2,10 @@
  * Return the second (0-59) from a UTC datetime string.
  *
  * - Returns zero-padded string for second.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Second (00-59) or "" on invalid input
  *
  * @example parseSecondFromUtc("2024-03-17T14:30:45Z") // "45"
@@ -15,5 +13,13 @@
  * @example parseSecondFromUtc("invalid") // ""
  */
 export declare function parseSecondFromUtc(value: string, options?: {
+    /**
+     * 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"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseSecondFromUtc.js

@@ -1,15 +1,13 @@
-import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { utcWallClock } from "../../internal/utcWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the second (0-59) from a UTC datetime string.
  *
  * - Returns zero-padded string for second.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA, default "UTC")
+ * @param options The time zone the value is read in
  * @returns Second (00-59) or "" on invalid input
  *
  * @example parseSecondFromUtc("2024-03-17T14:30:45Z") // "45"
@@ -21,7 +19,7 @@ export function parseSecondFromUtc(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const dateTime = utcZonedDateTime(value, options);
+        const dateTime = utcWallClock(value, options);
         return dateTime === null ? "" : dateTime.second.toString().padStart(2, "0");
     }
     catch {

package/dist/utc/parse/parseTimeFromUtc.d.ts

@@ -1,18 +1,26 @@
 /**
  * Extract the time portion from a UTC datetime string.
  *
- * - Uses Temporal.Instant.from to parse, converts to specified timezone.
- * - Defaults to UTC if no timezone specified.
+ * - Uses Temporal.Instant.from to parse, converts to the `timeZone` option's zone.
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA)
+ * @param options The time zone the value is read in
  * @returns ISO time string (e.g., "14:30:45") or "" on invalid input
  *
  * @example parseTimeFromUtc("2024-03-17T14:30:45Z") // "14:30:45"
  * @example parseTimeFromUtc("2024-03-17T14:30:45Z", { timeZone: "America/New_York" }) // "10:30:45"
  * @example parseTimeFromUtc("invalid") // ""
+ * @example parseTimeFromUtc("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export declare function parseTimeFromUtc(value: string, options?: {
+    /**
+     * 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"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseTimeFromUtc.js

@@ -1,21 +1,21 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../../zoned/index.js";
+import { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract the time portion from a UTC datetime string.
  *
- * - Uses Temporal.Instant.from to parse, converts to specified timezone.
- * - Defaults to UTC if no timezone specified.
+ * - Uses Temporal.Instant.from to parse, converts to the `timeZone` option's zone.
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param options optional: timeZone (IANA)
+ * @param options The time zone the value is read in
  * @returns ISO time string (e.g., "14:30:45") or "" on invalid input
  *
  * @example parseTimeFromUtc("2024-03-17T14:30:45Z") // "14:30:45"
  * @example parseTimeFromUtc("2024-03-17T14:30:45Z", { timeZone: "America/New_York" }) // "10:30:45"
  * @example parseTimeFromUtc("invalid") // ""
+ * @example parseTimeFromUtc("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export function parseTimeFromUtc(value, options) {
     try {
@@ -25,13 +25,13 @@ export function parseTimeFromUtc(value, options) {
         if (!isValidUtc(value)) {
             return "";
         }
-        const { timeZone = "UTC" } = options ?? {};
-        if (timeZone !== "UTC" && !isValidTimeZone(timeZone)) {
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null) {
             return "";
         }
         try {
             const instant = Temporal.Instant.from(value);
-            const dateTime = instant.toZonedDateTimeISO(timeZone);
+            const dateTime = frameWallClock(instant, frame);
             return dateTime.toPlainTime().toString();
         }
         catch {

package/dist/utc/parse/parseUnitFromUtc.d.ts

@@ -8,7 +8,7 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * | Member | Description |
  * | --- | --- |
- * | `year` | Full year, no padding (e.g. `2024`). |
+ * | `year` | Four digits (e.g. `2024`, `0005`); a sign and six digits outside 0000–9999 (e.g. `+010000`). |
  * | `month` | Zero-padded 2 (e.g. `03`). |
  * | `week` | Week-of-year, 1–53 (`weekStartsOn`-controlled). |
  * | `day` | Zero-padded 2. |
@@ -31,25 +31,44 @@ export type UtcUnit = Temporal.SmallestUnit<"year" | "month" | "week" | "day" |
  * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
- * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
- *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
+ * - A `"week"` in late December can be week 1 of the next year, under either week numbering.
+ * - `optionsArg` must be an object or omitted: a non-object value (such as `null`) returns "".
  * - Returns "" for invalid input.
+ * - 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 value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
  * @param unit unit to extract from the datetime
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations, timeZone (IANA, default "UTC"); a non-object value (such as `null`) is invalid
+ * @param optionsArg How weeks are numbered, and the time zone the value is read in
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromUtc("2024-03-17T14:30:45Z", "month") // "03"
  * @example parseUnitFromUtc("2024-03-17T14:30:45Z", "hours") // "14"
+ * @example parseUnitFromUtc("2024-03-17T14:30:45Z", "year") // "2024"
+ * @example parseUnitFromUtc("0005-06-01T12:30:00Z", "year") // "0005"
  * @example parseUnitFromUtc("2024-03-17T02:30:45Z", "day", { timeZone: "America/New_York" }) // "16"
  * @example parseUnitFromUtc("2024-01-01T00:00:00Z", "week") // "1"
  * @example parseUnitFromUtc("2024-12-31T12:00:00Z", "week", { weekStartsOn: "sunday" }) // "1"
  * @example parseUnitFromUtc("invalid", "month") // ""
+ * @example parseUnitFromUtc("1970-01-01T12:44:30Z", "minute", { timeZone: "-00:44:30" }) // "00" (a stored offset with seconds)
  */
 export declare function parseUnitFromUtc(value: string, unit: UtcUnit, optionsArg?: {
+    /**
+     * The first day of the week, which sets how the `"week"` unit is numbered. `"monday"` gives the
+     * ISO 8601 week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS
+     * #35 week number with a Sunday first day and one minimal day, where week 1 holds 1 January.
+     * Any other value returns `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
+    /**
+     * 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"`
+     */
     timeZone?: string;
 }): string;