@northguild/gmt 1.14.2 → 1.16.0

package/dist/utc/parse/parseDayOfWeekFromUtc.js

@@ -1,27 +1,45 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveReadingTimeZone } from "../../internal/resolveReadingTimeZone.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the day of week (1-7) from a UTC datetime string.
  *
  * - Monday=1 through Sunday=7.
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns Day of week (1-7) or null on invalid input
  *
  * @example parseDayOfWeekFromUtc("2024-03-17T14:30:45Z") // 7
  * @example parseDayOfWeekFromUtc("2024-03-18T00:00:00Z") // 1
+ * @example parseDayOfWeekFromUtc("2024-03-17T02:30:45Z", { timeZone: "America/New_York" }) // 6 (Saturday in New York)
  * @example parseDayOfWeekFromUtc("invalid") // null
  */
-export function parseDayOfWeekFromUtc(value) {
-    if (!isValidUtc(value))
-        return null;
+export function parseDayOfWeekFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return dateTime.dayOfWeek;
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        if (!isValidUtc(value))
+            return null;
+        const timeZone = resolveReadingTimeZone(options?.timeZone);
+        if (timeZone === null)
+            return null;
+        try {
+            const dateTime = Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
+            return dateTime.dayOfWeek;
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -2,12 +2,18 @@
  * 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")
  * @returns Hour (00-23) or "" on invalid input
  *
  * @example parseHourFromUtc("2024-03-17T14:30:45Z") // "14"
+ * @example parseHourFromUtc("2024-03-17T02:30:45Z", { timeZone: "America/New_York" }) // "22"
  * @example parseHourFromUtc("invalid") // ""
  */
-export declare function parseHourFromUtc(value: string): string;
+export declare function parseHourFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseHourFromUtc.js

@@ -1,26 +1,32 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../validate/index.js";
+import { utcZonedDateTime } from "../../internal/utcZonedDateTime.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")
  * @returns Hour (00-23) or "" on invalid input
  *
  * @example parseHourFromUtc("2024-03-17T14:30:45Z") // "14"
+ * @example parseHourFromUtc("2024-03-17T02:30:45Z", { timeZone: "America/New_York" }) // "22"
  * @example parseHourFromUtc("invalid") // ""
  */
-export function parseHourFromUtc(value) {
-    if (!isValidUtc(value))
-        return "";
+export function parseHourFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return dateTime.hour.toString().padStart(2, "0");
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const dateTime = utcZonedDateTime(value, options);
+        return dateTime === null ? "" : dateTime.hour.toString().padStart(2, "0");
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,24 +1,49 @@
 /**
- * Parse an RFC 7231 IMF-fixdate string — the fixed grammar HTTP headers like
+ * Parse an RFC 9110 HTTP-date — the fixed grammar HTTP headers like
  * `Last-Modified`/`Date`/`Expires` use — into a UTC ISO 8601 datetime string.
  *
- * - **Decoding, not display.** Accepts English weekday/month abbreviations
- *   only, per the fixed grammar (see `formatHttp`'s JSDoc and roadmap
- *   Decision 1).
- * - **IMF-fixdate only.** RFC 7231 also lists two obsolete forms
- *   (`rfc850-date`, `asctime-date`) that real HTTP servers occasionally
- *   still emit; this is a documented limitation — neither is accepted here.
- * - Day, hour, minute, and second must each be exactly 2 digits and the
- *   trailing zone must be the literal `GMT` — unlike `parseRfc2822`, no
- *   numeric offset or named-zone table is accepted.
- * - The day-of-week is not cross-validated against the computed date, the
- *   same deliberate scope limit `parseDateTimeWithPattern`/J11 uses.
+ * - **Decoding, not display.** Accepts English weekday/month names only, per
+ *   the fixed grammar (see `formatHttp`'s JSDoc and roadmap Decision 1).
+ * - **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
+ *   rfc850-date (`Sunday, 06-Nov-94 08:49:37 GMT`) and asctime-date
+ *   (`Sun Nov  6 08:49:37 1994`, read as UTC).
+ * - HTTP-date is case-sensitive and fixed-width: exactly the spacing, digit
+ *   counts and the literal `GMT` of the grammar. No numeric offset is
+ *   accepted.
+ * - **rfc850-date years read the clock.** Its two-digit year becomes the
+ *   latest year ending in those digits whose timestamp is not more than 50
+ *   years after now (`Temporal.Now.instant()`), per RFC 9110: "a timestamp
+ *   that appears to be more than 50 years in the future" is "the most recent
+ *   year in the past that had the same last two digits". The same string can
+ *   therefore parse differently decades apart; if the clock cannot be read
+ *   the result is `""`.
+ * - **The day name must match the date, in all three formats.** RFC 9110 gives it
+ *   RFC 5322's semantics: "the day-of-week (if included) MUST be the day implied by
+ *   the date". A mismatch returns `""` — deliberately in asctime-date too, where the
+ *   day name is not separated by a comma and so is easy to overlook. `Mon Nov  6
+ *   08:49:37 1994` is `""`, exactly as `Mon, 06 Nov 1994 08:49:37 GMT` and
+ *   `Monday, 06-Nov-94 08:49:37 GMT` are: 6 November 1994 was a Sunday. A parser that
+ *   accepted the mismatch would have to pick which of the two fields to believe, and
+ *   there is no rule in RFC 9110 that says which.
+ * - An impossible calendar date (`31 Feb`, `29 Feb 2023`) returns `""`: a parser never
+ *   invents a date, so fields are validated with `overflow: "reject"`, not clamped.
+ * - For the IMF-fixdate shape alone, test the exported `httpDate` pattern.
+ * - **Compatibility:** before 1.16.0 a day name that did not match the date was ignored.
+ *   Parse the same fields as an RFC 5322 date-time without the day name, then convert.
  *
- * @param value RFC 7231 IMF-fixdate string (e.g. "Fri, 15 Mar 2024 14:30:00 GMT")
+ * @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("Fri, 15 Mar 2024 14:30:00 -0400") // "" (not IMF-fixdate)
+ * @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 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") // ""
  */
 export declare function parseHttp(value: string): string;

package/dist/utc/parse/parseHttp.js

@@ -1,51 +1,92 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { ENGLISH_MONTH_NAMES } from "../../internal/index.js";
+import { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES } from "../../internal/index.js";
+import { readObsoleteHttpDate, } from "../../internal/httpDateFields.js";
 import { httpDate } from "../../regex/index.js";
 /**
- * Parse an RFC 7231 IMF-fixdate string — the fixed grammar HTTP headers like
+ * Parse an RFC 9110 HTTP-date — the fixed grammar HTTP headers like
  * `Last-Modified`/`Date`/`Expires` use — into a UTC ISO 8601 datetime string.
  *
- * - **Decoding, not display.** Accepts English weekday/month abbreviations
- *   only, per the fixed grammar (see `formatHttp`'s JSDoc and roadmap
- *   Decision 1).
- * - **IMF-fixdate only.** RFC 7231 also lists two obsolete forms
- *   (`rfc850-date`, `asctime-date`) that real HTTP servers occasionally
- *   still emit; this is a documented limitation — neither is accepted here.
- * - Day, hour, minute, and second must each be exactly 2 digits and the
- *   trailing zone must be the literal `GMT` — unlike `parseRfc2822`, no
- *   numeric offset or named-zone table is accepted.
- * - The day-of-week is not cross-validated against the computed date, the
- *   same deliberate scope limit `parseDateTimeWithPattern`/J11 uses.
+ * - **Decoding, not display.** Accepts English weekday/month names only, per
+ *   the fixed grammar (see `formatHttp`'s JSDoc and roadmap Decision 1).
+ * - **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
+ *   rfc850-date (`Sunday, 06-Nov-94 08:49:37 GMT`) and asctime-date
+ *   (`Sun Nov  6 08:49:37 1994`, read as UTC).
+ * - HTTP-date is case-sensitive and fixed-width: exactly the spacing, digit
+ *   counts and the literal `GMT` of the grammar. No numeric offset is
+ *   accepted.
+ * - **rfc850-date years read the clock.** Its two-digit year becomes the
+ *   latest year ending in those digits whose timestamp is not more than 50
+ *   years after now (`Temporal.Now.instant()`), per RFC 9110: "a timestamp
+ *   that appears to be more than 50 years in the future" is "the most recent
+ *   year in the past that had the same last two digits". The same string can
+ *   therefore parse differently decades apart; if the clock cannot be read
+ *   the result is `""`.
+ * - **The day name must match the date, in all three formats.** RFC 9110 gives it
+ *   RFC 5322's semantics: "the day-of-week (if included) MUST be the day implied by
+ *   the date". A mismatch returns `""` — deliberately in asctime-date too, where the
+ *   day name is not separated by a comma and so is easy to overlook. `Mon Nov  6
+ *   08:49:37 1994` is `""`, exactly as `Mon, 06 Nov 1994 08:49:37 GMT` and
+ *   `Monday, 06-Nov-94 08:49:37 GMT` are: 6 November 1994 was a Sunday. A parser that
+ *   accepted the mismatch would have to pick which of the two fields to believe, and
+ *   there is no rule in RFC 9110 that says which.
+ * - An impossible calendar date (`31 Feb`, `29 Feb 2023`) returns `""`: a parser never
+ *   invents a date, so fields are validated with `overflow: "reject"`, not clamped.
+ * - For the IMF-fixdate shape alone, test the exported `httpDate` pattern.
+ * - **Compatibility:** before 1.16.0 a day name that did not match the date was ignored.
+ *   Parse the same fields as an RFC 5322 date-time without the day name, then convert.
  *
- * @param value RFC 7231 IMF-fixdate string (e.g. "Fri, 15 Mar 2024 14:30:00 GMT")
+ * @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("Fri, 15 Mar 2024 14:30:00 -0400") // "" (not IMF-fixdate)
+ * @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 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") // ""
  */
 export function parseHttp(value) {
     if (typeof value !== "string")
         return "";
-    const match = httpDate.exec(value);
-    if (match === null)
-        return "";
-    const [, , dayStr, monthName, yearStr, hourStr, minuteStr, secondStr] = match;
-    const monthIndex = ENGLISH_MONTH_NAMES.indexOf(monthName);
-    if (monthIndex === -1)
-        return "";
     try {
+        const fields = readHttpDate(value);
+        if (fields === null)
+            return "";
         const plainDateTime = Temporal.PlainDateTime.from({
-            year: Number(yearStr),
-            month: monthIndex + 1,
-            day: Number(dayStr),
-            hour: Number(hourStr),
-            minute: Number(minuteStr),
-            second: Number(secondStr),
+            year: fields.year,
+            month: fields.month,
+            day: fields.day,
+            hour: fields.hour,
+            minute: fields.minute,
+            second: fields.second,
         }, { overflow: "reject" });
+        // RFC 9110 gives day-name RFC 5322's semantics: "the day-of-week (if
+        // included) MUST be the day implied by the date".
+        if (fields.dayOfWeek !== plainDateTime.dayOfWeek)
+            return "";
         return plainDateTime.toZonedDateTime("UTC").toInstant().toString();
     }
     catch {
         return "";
     }
 }
+function readHttpDate(value) {
+    const match = httpDate.exec(value);
+    if (match === null)
+        return readObsoleteHttpDate(value);
+    const [, dayName, day, month, year, hour, minute, second] = match;
+    return {
+        dayOfWeek: ENGLISH_WEEKDAY_NAMES.indexOf(dayName) + 1,
+        year: Number(year),
+        month: ENGLISH_MONTH_NAMES.indexOf(month) + 1,
+        day: Number(day),
+        hour: Number(hour),
+        minute: Number(minute),
+        second: Number(second),
+    };
+}

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

@@ -2,12 +2,19 @@
  * 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")
  * @returns Microsecond (000-999) or "" on invalid input
  *
- * @example parseMicrosecondFromUtc("2024-03-17T14:30:45.123Z") // "123"
+ * @example parseMicrosecondFromUtc("2024-03-17T14:30:45.123Z") // "000"
+ * @example parseMicrosecondFromUtc("2024-03-17T14:30:45.123456Z") // "456"
+ * @example parseMicrosecondFromUtc("2024-03-17T14:30:45.123456Z", { timeZone: "America/New_York" }) // "456"
  * @example parseMicrosecondFromUtc("invalid") // ""
  */
-export declare function parseMicrosecondFromUtc(value: string): string;
+export declare function parseMicrosecondFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseMicrosecondFromUtc.js

@@ -1,26 +1,35 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../validate/index.js";
+import { utcZonedDateTime } from "../../internal/utcZonedDateTime.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")
  * @returns Microsecond (000-999) or "" on invalid input
  *
- * @example parseMicrosecondFromUtc("2024-03-17T14:30:45.123Z") // "123"
+ * @example parseMicrosecondFromUtc("2024-03-17T14:30:45.123Z") // "000"
+ * @example parseMicrosecondFromUtc("2024-03-17T14:30:45.123456Z") // "456"
+ * @example parseMicrosecondFromUtc("2024-03-17T14:30:45.123456Z", { timeZone: "America/New_York" }) // "456"
  * @example parseMicrosecondFromUtc("invalid") // ""
  */
-export function parseMicrosecondFromUtc(value) {
-    if (!isValidUtc(value))
-        return "";
+export function parseMicrosecondFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return (dateTime.microsecond ?? 0).toString().padStart(3, "0");
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const dateTime = utcZonedDateTime(value, options);
+        return dateTime === null
+            ? ""
+            : dateTime.microsecond.toString().padStart(3, "0");
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -2,12 +2,18 @@
  * 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")
  * @returns Millisecond (000-999) or "" on invalid input
  *
  * @example parseMillisecondFromUtc("2024-03-17T14:30:45.123Z") // "123"
+ * @example parseMillisecondFromUtc("2024-03-17T14:30:45.123Z", { timeZone: "America/New_York" }) // "123"
  * @example parseMillisecondFromUtc("invalid") // ""
  */
-export declare function parseMillisecondFromUtc(value: string): string;
+export declare function parseMillisecondFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseMillisecondFromUtc.js

@@ -1,26 +1,34 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../validate/index.js";
+import { utcZonedDateTime } from "../../internal/utcZonedDateTime.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")
  * @returns Millisecond (000-999) or "" on invalid input
  *
  * @example parseMillisecondFromUtc("2024-03-17T14:30:45.123Z") // "123"
+ * @example parseMillisecondFromUtc("2024-03-17T14:30:45.123Z", { timeZone: "America/New_York" }) // "123"
  * @example parseMillisecondFromUtc("invalid") // ""
  */
-export function parseMillisecondFromUtc(value) {
-    if (!isValidUtc(value))
-        return "";
+export function parseMillisecondFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return dateTime.millisecond.toString().padStart(3, "0");
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const dateTime = utcZonedDateTime(value, options);
+        return dateTime === null
+            ? ""
+            : dateTime.millisecond.toString().padStart(3, "0");
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -2,12 +2,18 @@
  * 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")
  * @returns Minute (00-59) or "" on invalid input
  *
  * @example parseMinuteFromUtc("2024-03-17T14:30:45Z") // "30"
+ * @example parseMinuteFromUtc("2024-03-17T02:30:45Z", { timeZone: "Asia/Kolkata" }) // "00"
  * @example parseMinuteFromUtc("invalid") // ""
  */
-export declare function parseMinuteFromUtc(value: string): string;
+export declare function parseMinuteFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseMinuteFromUtc.js

@@ -1,26 +1,32 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../validate/index.js";
+import { utcZonedDateTime } from "../../internal/utcZonedDateTime.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")
  * @returns Minute (00-59) or "" on invalid input
  *
  * @example parseMinuteFromUtc("2024-03-17T14:30:45Z") // "30"
+ * @example parseMinuteFromUtc("2024-03-17T02:30:45Z", { timeZone: "Asia/Kolkata" }) // "00"
  * @example parseMinuteFromUtc("invalid") // ""
  */
-export function parseMinuteFromUtc(value) {
-    if (!isValidUtc(value))
-        return "";
+export function parseMinuteFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return dateTime.minute.toString().padStart(2, "0");
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const dateTime = utcZonedDateTime(value, options);
+        return dateTime === null ? "" : dateTime.minute.toString().padStart(2, "0");
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -2,12 +2,18 @@
  * 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")
  * @returns Month (01-12) or "" on invalid input
  *
  * @example parseMonthFromUtc("2024-03-17T14:30:45Z") // "03"
+ * @example parseMonthFromUtc("2025-01-01T02:00:00Z", { timeZone: "America/New_York" }) // "12"
  * @example parseMonthFromUtc("invalid") // ""
  */
-export declare function parseMonthFromUtc(value: string): string;
+export declare function parseMonthFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseMonthFromUtc.js

@@ -1,26 +1,32 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../validate/index.js";
+import { utcZonedDateTime } from "../../internal/utcZonedDateTime.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")
  * @returns Month (01-12) or "" on invalid input
  *
  * @example parseMonthFromUtc("2024-03-17T14:30:45Z") // "03"
+ * @example parseMonthFromUtc("2025-01-01T02:00:00Z", { timeZone: "America/New_York" }) // "12"
  * @example parseMonthFromUtc("invalid") // ""
  */
-export function parseMonthFromUtc(value) {
-    if (!isValidUtc(value))
-        return "";
+export function parseMonthFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return dateTime.month.toString().padStart(2, "0");
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const dateTime = utcZonedDateTime(value, options);
+        return dateTime === null ? "" : dateTime.month.toString().padStart(2, "0");
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -2,12 +2,19 @@
  * 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")
  * @returns Nanosecond (000-999) or "" on invalid input
  *
- * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123Z") // "123000000"
+ * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123Z") // "000"
+ * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123456789Z") // "789"
+ * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123456789Z", { timeZone: "America/New_York" }) // "789"
  * @example parseNanosecondFromUtc("invalid") // ""
  */
-export declare function parseNanosecondFromUtc(value: string): string;
+export declare function parseNanosecondFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseNanosecondFromUtc.js

@@ -1,26 +1,35 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../validate/index.js";
+import { utcZonedDateTime } from "../../internal/utcZonedDateTime.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")
  * @returns Nanosecond (000-999) or "" on invalid input
  *
- * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123Z") // "123000000"
+ * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123Z") // "000"
+ * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123456789Z") // "789"
+ * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123456789Z", { timeZone: "America/New_York" }) // "789"
  * @example parseNanosecondFromUtc("invalid") // ""
  */
-export function parseNanosecondFromUtc(value) {
-    if (!isValidUtc(value))
-        return "";
+export function parseNanosecondFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return (dateTime.nanosecond ?? 0).toString().padStart(3, "0");
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const dateTime = utcZonedDateTime(value, options);
+        return dateTime === null
+            ? ""
+            : dateTime.nanosecond.toString().padStart(3, "0");
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }