@northguild/gmt 1.17.0 → 1.18.0

package/dist/utc/parse/parseHttp.js

@@ -7,7 +7,7 @@ import { httpDate } from "../../regex/index.js";
  * `Last-Modified`/`Date`/`Expires` use — 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 `formatHttp`'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

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,11 @@
  * @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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseMicrosecondFromUtc.js

@@ -4,12 +4,10 @@ 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"

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,11 @@
  * @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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseMillisecondFromUtc.js

@@ -4,12 +4,10 @@ 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"

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,11 @@
  * @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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseMinuteFromUtc.js

@@ -4,12 +4,10 @@ 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"

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,11 @@
  * @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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseMonthFromUtc.js

@@ -4,12 +4,10 @@ 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"

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,11 @@
  * @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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseNanosecondFromUtc.js

@@ -4,12 +4,10 @@ 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"

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,11 @@
  * @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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseSecondFromUtc.js

@@ -4,12 +4,10 @@ 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"

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

@@ -1,12 +1,11 @@
 /**
  * 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"
@@ -14,5 +13,11 @@
  * @example parseTimeFromUtc("invalid") // ""
  */
 export declare function parseTimeFromUtc(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 `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseTimeFromUtc.js

@@ -1,16 +1,15 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../../zoned/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.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"
@@ -25,8 +24,8 @@ export function parseTimeFromUtc(value, options) {
         if (!isValidUtc(value)) {
             return "";
         }
-        const { timeZone = "UTC" } = options ?? {};
-        if (timeZone !== "UTC" && !isValidTimeZone(timeZone)) {
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (timeZone === "") {
             return "";
         }
         try {

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

@@ -31,15 +31,13 @@ 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.
  *
  * @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"
@@ -50,6 +48,20 @@ export type UtcUnit = Temporal.SmallestUnit<"year" | "month" | "week" | "day" |
  * @example parseUnitFromUtc("invalid", "month") // ""
  */
 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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseUnitFromUtc.js

@@ -1,7 +1,7 @@
 // fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
-import { resolveReadingTimeZone } from "../../internal/resolveReadingTimeZone.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { isValidUtc } from "../validate/index.js";
@@ -12,15 +12,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - 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.
  *
  * @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"
@@ -37,8 +35,8 @@ export function parseUnitFromUtc(value, unit, optionsArg) {
             return "";
         }
         const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
-        const timeZone = resolveReadingTimeZone(optionsArg?.timeZone);
-        if (!isValidUtc(value) || weekStartsOn === null || timeZone === null) {
+        const timeZone = normalizeTimeZone(optionsArg?.timeZone);
+        if (!isValidUtc(value) || weekStartsOn === null || timeZone === "") {
             return "";
         }
         try {

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

@@ -1,19 +1,13 @@
 /**
  * Return the week number from a UTC datetime string.
  *
- * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
- *   first Thursday, so late-December days can be week 1 of the next year (a value on 2024-12-31
- *   → 1). The result is 1–53.
- * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
- *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
- *   next year (2024-12-31 → 1, 2000-12-30 → 53). The result is 1–53.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
- * - The week is read from the value's date on the wall clock of `options.timeZone` (an IANA zone,
- *   default UTC), as `parseTimeFromUtc` does; an invalid zone returns null.
+ * - The result is the week of the week-year, 1–53, so late-December days can be week 1 of the next
+ *   year: 2024-12-31 → 1 under either numbering, and 2000-12-30 → 53 under the Sunday-first one
+ *   (minimal days 1).
  * - Returns null for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations, timeZone (IANA, default "UTC")
+ * @param optionsArg How weeks are numbered, and the time zone the value is read in
  * @returns Week number (1-53), or null on invalid input
  *
  * @example parseWeekFromUtc("2024-03-17T14:30:45Z") // 11
@@ -24,6 +18,20 @@
  * @example parseWeekFromUtc("invalid") // null
  */
 export declare function parseWeekFromUtc(value: string, optionsArg?: {
+    /**
+     * The first day of the week, which sets how the week 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 `null`.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
+    /**
+     * 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 `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): number | null;

package/dist/utc/parse/parseWeekFromUtc.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveReadingTimeZone } from "../../internal/resolveReadingTimeZone.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { isValidUtc } from "../validate/index.js";
@@ -7,19 +7,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number from a UTC datetime string.
  *
- * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
- *   first Thursday, so late-December days can be week 1 of the next year (a value on 2024-12-31
- *   → 1). The result is 1–53.
- * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
- *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
- *   next year (2024-12-31 → 1, 2000-12-30 → 53). The result is 1–53.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
- * - The week is read from the value's date on the wall clock of `options.timeZone` (an IANA zone,
- *   default UTC), as `parseTimeFromUtc` does; an invalid zone returns null.
+ * - The result is the week of the week-year, 1–53, so late-December days can be week 1 of the next
+ *   year: 2024-12-31 → 1 under either numbering, and 2000-12-30 → 53 under the Sunday-first one
+ *   (minimal days 1).
  * - Returns null for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations, timeZone (IANA, default "UTC")
+ * @param optionsArg How weeks are numbered, and the time zone the value is read in
  * @returns Week number (1-53), or null on invalid input
  *
  * @example parseWeekFromUtc("2024-03-17T14:30:45Z") // 11
@@ -37,8 +31,8 @@ export function parseWeekFromUtc(value, optionsArg) {
         if (!isValidUtc(value))
             return null;
         const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
-        const timeZone = resolveReadingTimeZone(optionsArg?.timeZone);
-        if (weekStartsOn === null || timeZone === null)
+        const timeZone = normalizeTimeZone(optionsArg?.timeZone);
+        if (weekStartsOn === null || timeZone === "")
             return null;
         try {
             const instant = Temporal.Instant.from(value);

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

@@ -2,12 +2,10 @@
  * Return the year from a UTC datetime string.
  *
  * - Returns the year as a string (e.g., "2024").
- * - 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 Year (YYYY) or "" on invalid input
  *
  * @example parseYearFromUtc("2024-03-17T14:30:45Z") // "2024"
@@ -15,5 +13,11 @@
  * @example parseYearFromUtc("invalid") // ""
  */
 export declare function parseYearFromUtc(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 `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/utc/parse/parseYearFromUtc.js

@@ -4,12 +4,10 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the year from a UTC datetime string.
  *
  * - Returns the year as a string (e.g., "2024").
- * - 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 Year (YYYY) or "" on invalid input
  *
  * @example parseYearFromUtc("2024-03-17T14:30:45Z") // "2024"

package/dist/utc/validate/isValidUtcRange.d.ts

@@ -1,16 +1,13 @@
 /**
  * Return true if `value1` and `value2` form a valid UTC range — both parseable as
- * ISO UTC datetime strings and the instant at `value1` is <= the instant at `value2`.
+ * ISO UTC datetime strings and the instant at `value1` is before the instant at `value2`.
  *
  * - Both inputs must be ISO 8601 UTC datetime strings (e.g. `"2024-01-01T10:00:00Z"`), as
  *   `isValidUtc` accepts, annotations included.
- * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Leap-second strings return `false`.
  * - Invalid input or malformed strings return `false`.
  *
- * @param value1 first ISO UTC datetime string
- * @param value2 second ISO UTC datetime string
- * @param options optional allowEqual flag
+ * @param props The two ends of the range, and whether equal ends are valid
  * @returns boolean indicating whether the UTC range is valid
  *
  * @example isValidUtcRange({ value1: "2024-01-01T10:00:00Z", value2: "2024-12-31T23:59:59Z" }) // true
@@ -18,9 +15,23 @@
  * @example isValidUtcRange({ value1: "2024-01-01T10:00:00Z", value2: "2024-01-01T10:00:00Z", options: { allowEqual: true } }) // true
  */
 export declare function isValidUtcRange(props: {
+    /** The start of the range, as an ISO UTC datetime string. */
     value1: string;
+    /** The end of the range, as an ISO UTC datetime string. */
     value2: string;
+    /**
+     * The settings for the comparison. It must be an object or omitted; any other value, `null`
+     * included, returns `false`.
+     *
+     * @defaultValue None. Two values at the same instant are not a valid range.
+     */
     options?: {
+        /**
+         * Whether `value1` at the same instant as `value2` is a valid range. `false` requires `value1`
+         * to be before `value2`.
+         *
+         * @defaultValue `false`
+         */
         allowEqual?: boolean;
     };
 }): boolean;

package/dist/utc/validate/isValidUtcRange.js

@@ -4,17 +4,14 @@ import { isValidUtc } from "./isValidUtc.js";
 import { isObject, isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true if `value1` and `value2` form a valid UTC range — both parseable as
- * ISO UTC datetime strings and the instant at `value1` is <= the instant at `value2`.
+ * ISO UTC datetime strings and the instant at `value1` is before the instant at `value2`.
  *
  * - Both inputs must be ISO 8601 UTC datetime strings (e.g. `"2024-01-01T10:00:00Z"`), as
  *   `isValidUtc` accepts, annotations included.
- * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Leap-second strings return `false`.
  * - Invalid input or malformed strings return `false`.
  *
- * @param value1 first ISO UTC datetime string
- * @param value2 second ISO UTC datetime string
- * @param options optional allowEqual flag
+ * @param props The two ends of the range, and whether equal ends are valid
  * @returns boolean indicating whether the UTC range is valid
  *
  * @example isValidUtcRange({ value1: "2024-01-01T10:00:00Z", value2: "2024-12-31T23:59:59Z" }) // true