@northguild/gmt 1.17.0 → 1.19.0

package/dist/utc/get/getUtcYear.js

@@ -1,24 +1,17 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Return the current year from UTC as a zero-padded string.
  *
  * - 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 function getUtcYear() {
-    try {
-        return Temporal.Now.instant()
-            .toZonedDateTimeISO("UTC")
-            .year.toString()
-            .padStart(4, "0");
-    }
-    catch {
-        return "";
-    }
+    return isoYearString(Temporal.Now.instant().toZonedDateTimeISO("UTC").year);
 }

package/dist/utc/interval/intervalDifferenceUtc.d.ts

@@ -27,6 +27,12 @@
  * @example intervalDifferenceUtc("invalid", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // []
  */
 export declare function intervalDifferenceUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/utc/interval/intervalDivideEquallyUtc.d.ts

@@ -10,18 +10,19 @@
  *   split is exact whenever the span divides evenly by `n` and within half a nanosecond of the
  *   exact cut otherwise, at any span length (no double arithmetic) — no DST is involved, since
  *   UTC has no time zone offset.
+ * - When `n` is larger than the number of nanoseconds in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`, leap-second strings).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
+ * - Returns `[]` before building any piece when `n` exceeds the longest possible array
+ *   (2^32 - 1).
  *
  * @param start ISO UTC datetime string for the interval start
  * @param end ISO UTC datetime string for the interval end
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options A limit on the size of the result
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, { start: "2024-01-02T00:00:00Z", end: "2024-01-03T00:00:00Z" }, { start: "2024-01-03T00:00:00Z", end: "2024-01-04T00:00:00Z" }]
@@ -32,8 +33,21 @@
  * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3, { maxPieces: 3 }) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, { start: "2024-01-02T00:00:00Z", end: "2024-01-03T00:00:00Z" }, { start: "2024-01-03T00:00:00Z", end: "2024-01-04T00:00:00Z" }]
  */
 export declare function intervalDivideEquallyUtc(start: string, end: string, n: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 }>;

package/dist/utc/interval/intervalDivideEquallyUtc.js

@@ -15,18 +15,19 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  *   split is exact whenever the span divides evenly by `n` and within half a nanosecond of the
  *   exact cut otherwise, at any span length (no double arithmetic) — no DST is involved, since
  *   UTC has no time zone offset.
+ * - When `n` is larger than the number of nanoseconds in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`, leap-second strings).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
+ * - Returns `[]` before building any piece when `n` exceeds the longest possible array
+ *   (2^32 - 1).
  *
  * @param start ISO UTC datetime string for the interval start
  * @param end ISO UTC datetime string for the interval end
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options A limit on the size of the result
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, { start: "2024-01-02T00:00:00Z", end: "2024-01-03T00:00:00Z" }, { start: "2024-01-03T00:00:00Z", end: "2024-01-04T00:00:00Z" }]

package/dist/utc/interval/intervalFromDurationUtc.d.ts

@@ -10,15 +10,13 @@ import type { Overflow } from "../../types/index.js";
  *   reference point (mirrors `addUtc`).
  * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
  *   happens, mirroring `intervalIntersectionUtc`'s `start > end` rejection.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
  * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
  *   than `"start"`/`"end"`).
  *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns `{ start, end }` with the constructed span (UTC Instant strings), or null on invalid input
  *
  * @example intervalFromDurationUtc("2024-01-01T00:00:00Z", "P1D", "start") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }
@@ -28,8 +26,20 @@ import type { Overflow } from "../../types/index.js";
  * @example intervalFromDurationUtc("invalid", "P1D", "start") // null
  */
 export declare function intervalFromDurationUtc(value: string, duration: string, anchor: "start" | "end", options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so Jan 31 + 1 month is Feb 29/28 (TC39 Temporal); `"reject"` returns `null`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): {
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 } | null;

package/dist/utc/interval/intervalFromDurationUtc.js

@@ -15,15 +15,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   reference point (mirrors `addUtc`).
  * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
  *   happens, mirroring `intervalIntersectionUtc`'s `start > end` rejection.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
  * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
  *   than `"start"`/`"end"`).
  *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns `{ start, end }` with the constructed span (UTC Instant strings), or null on invalid input
  *
  * @example intervalFromDurationUtc("2024-01-01T00:00:00Z", "P1D", "start") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }

package/dist/utc/interval/intervalIntersectionUtc.d.ts

@@ -24,6 +24,12 @@
  * @example intervalIntersectionUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
  */
 export declare function intervalIntersectionUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): {
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 } | null;

package/dist/utc/interval/intervalSplitAtUtc.d.ts

@@ -13,6 +13,8 @@
  *   there, so the pieces share no value and together cover the interval exactly once (the rule
  *   CORE-6's `splitIntervalAt` uses).
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
+ * - A piece's `end` equals its `start` only when the interval itself is zero-length (`start`
+ *   equal to `end`): the result is then that one empty piece, whatever the points.
  * - Returns `[]` when `points` is not an array, when any element is not a valid ISO UTC
  *   datetime string, or on invalid input (unparseable start/end, `start > end`, leap-second
  *   strings).
@@ -27,6 +29,12 @@
  * @example intervalSplitAtUtc("invalid", "2024-01-10T00:00:00Z", ["2024-01-05T00:00:00Z"]) // []
  */
 export declare function intervalSplitAtUtc(start: string, end: string, points: string[]): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 }>;

package/dist/utc/interval/intervalSplitAtUtc.js

@@ -16,6 +16,8 @@ import { isValidUtc } from "../validate/index.js";
  *   there, so the pieces share no value and together cover the interval exactly once (the rule
  *   CORE-6's `splitIntervalAt` uses).
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
+ * - A piece's `end` equals its `start` only when the interval itself is zero-length (`start`
+ *   equal to `end`): the result is then that one empty piece, whatever the points.
  * - Returns `[]` when `points` is not an array, when any element is not a valid ISO UTC
  *   datetime string, or on invalid input (unparseable start/end, `start > end`, leap-second
  *   strings).

package/dist/utc/interval/intervalUnionUtc.d.ts

@@ -27,6 +27,12 @@
  * @example intervalUnionUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
  */
 export declare function intervalUnionUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): {
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 } | null;

package/dist/utc/interval/intervalXorAllUtc.d.ts

@@ -26,6 +26,12 @@ export declare function intervalXorAllUtc(intervals: Array<{
     start: string;
     end: string;
 }>): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/utc/interval/intervalXorAllUtc.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { halfOpenXor } from "../../internal/index.js";
 import { isValidUtcInterval } from "./validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Return the symmetric difference across a list of UTC intervals — the set of instants covered
  * by an odd number of the input intervals.
@@ -30,8 +31,7 @@ export function intervalXorAllUtc(intervals) {
         if (!Array.isArray(intervals) || intervals.length === 0) {
             return [];
         }
-        if (!intervals.every((interval) => interval &&
-            typeof interval === "object" &&
+        if (!intervals.every((interval) => isObject(interval) &&
             typeof interval.start === "string" &&
             typeof interval.end === "string" &&
             isValidUtcInterval(interval.start, interval.end))) {

package/dist/utc/interval/intervalXorUtc.d.ts

@@ -22,6 +22,12 @@
  * @example intervalXorUtc("invalid", "2024-06-30T12:00:00Z", "2024-07-01T13:00:00Z", "2024-12-31T17:00:00Z") // []
  */
 export declare function intervalXorUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/utc/interval/mergeIntervalsUtc.d.ts

@@ -27,6 +27,12 @@ export declare function mergeIntervalsUtc(intervals: Array<{
     start: string;
     end: string;
 }>): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/utc/interval/mergeIntervalsUtc.js

@@ -1,6 +1,7 @@
 import { canonicalInstantIntervals } from "../../internal/index.js";
 import { mergeIntervals } from "../../interval/calculate/index.js";
 import { isValidUtcInterval } from "./validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Collapse a list of UTC intervals into the minimum set of non-overlapping intervals.
  *
@@ -31,8 +32,7 @@ export function mergeIntervalsUtc(intervals) {
         if (!Array.isArray(intervals) || intervals.length === 0) {
             return [];
         }
-        if (!intervals.every((interval) => interval &&
-            typeof interval === "object" &&
+        if (!intervals.every((interval) => isObject(interval) &&
             typeof interval.start === "string" &&
             typeof interval.end === "string" &&
             isValidUtcInterval(interval.start, interval.end))) {

package/dist/utc/interval/splitIntervalByUnitUtc.d.ts

@@ -8,8 +8,11 @@
  *   CORE-6's `splitIntervalAt` uses).
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
  * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
- *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ *   (`start + k × amount`), so month-end starts don't drift: a monthly split from January 31
+ *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
+ *   to the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER`.
@@ -18,15 +21,12 @@
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
  *   leap-second strings).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
  *
  * @param start ISO UTC datetime string for the interval start
  * @param end ISO UTC datetime string for the interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options A limit on the size of the result
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "hour", 6) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T06:00:00Z" }, { start: "2024-01-01T06:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }, { start: "2024-01-01T18:00:00Z", end: "2024-01-02T00:00:00Z" }]
@@ -39,8 +39,21 @@
  * @example splitIntervalByUnitUtc("+275760-09-12T23:00:00Z", "+275760-09-13T00:00:00Z", "hour", 2) // [{ start: "+275760-09-12T23:00:00Z", end: "+275760-09-13T00:00:00Z" }] (the step past the last instant is trimmed to `end`)
  */
 export declare function splitIntervalByUnitUtc(start: string, end: string, unit: string, amount: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): Array<{
+    /** The instant the interval begins at, as an ISO 8601 UTC string ending in `Z`. */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 }>;

package/dist/utc/interval/splitIntervalByUnitUtc.js

@@ -15,8 +15,11 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  *   CORE-6's `splitIntervalAt` uses).
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
  * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
- *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ *   (`start + k × amount`), so month-end starts don't drift: a monthly split from January 31
+ *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
+ *   to the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER`.
@@ -25,15 +28,12 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
  *   leap-second strings).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
  *
  * @param start ISO UTC datetime string for the interval start
  * @param end ISO UTC datetime string for the interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options A limit on the size of the result
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "hour", 6) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T06:00:00Z" }, { start: "2024-01-01T06:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }, { start: "2024-01-01T18:00:00Z", end: "2024-01-02T00:00:00Z" }]

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

@@ -2,7 +2,7 @@ export * from "./parseDateFromUtc.js";
 export * from "./parseDayFromUtc.js";
 export * from "./parseDayOfWeekFromUtc.js";
 export * from "./parseHourFromUtc.js";
-export * from "./parseHttp.js";
+export * from "./parseHttpDate.js";
 export * from "./parseMicrosecondFromUtc.js";
 export * from "./parseMillisecondFromUtc.js";
 export * from "./parseMinuteFromUtc.js";

package/dist/utc/parse/index.js

@@ -2,7 +2,7 @@ export * from "./parseDateFromUtc.js";
 export * from "./parseDayFromUtc.js";
 export * from "./parseDayOfWeekFromUtc.js";
 export * from "./parseHourFromUtc.js";
-export * from "./parseHttp.js";
+export * from "./parseHttpDate.js";
 export * from "./parseMicrosecondFromUtc.js";
 export * from "./parseMillisecondFromUtc.js";
 export * from "./parseMinuteFromUtc.js";

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

@@ -2,12 +2,10 @@
  * Extract the date portion from a UTC datetime string.
  *
  * - Uses Temporal.Instant.from to parse, converts to UTC date.
- * - 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 ISO date string (e.g., "2024-03-17") or "" on invalid input
  *
  * @example parseDateFromUtc("2024-03-17T14:30:45Z") // "2024-03-17"
@@ -15,5 +13,13 @@
  * @example parseDateFromUtc("invalid") // ""
  */
 export declare function parseDateFromUtc(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/parseDateFromUtc.js

@@ -1,15 +1,13 @@
-import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { utcWallClock } from "../../internal/utcWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract the date portion from a UTC datetime string.
  *
  * - Uses Temporal.Instant.from to parse, converts to UTC date.
- * - 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 ISO date string (e.g., "2024-03-17") or "" on invalid input
  *
  * @example parseDateFromUtc("2024-03-17T14:30:45Z") // "2024-03-17"
@@ -21,7 +19,7 @@ export function parseDateFromUtc(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const dateTime = utcZonedDateTime(value, options);
+        const dateTime = utcWallClock(value, options);
         return dateTime === null ? "" : dateTime.toPlainDate().toString();
     }
     catch {

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

@@ -2,12 +2,10 @@
  * Return the day of month (1-31) from a UTC datetime string.
  *
  * - Returns zero-padded string for day.
- * - 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 Day (01-31) or "" on invalid input
  *
  * @example parseDayFromUtc("2024-03-17T14:30:45Z") // "17"
@@ -15,5 +13,13 @@
  * @example parseDayFromUtc("invalid") // ""
  */
 export declare function parseDayFromUtc(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/parseDayFromUtc.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 day of month (1-31) from a UTC datetime string.
  *
  * - Returns zero-padded string for day.
- * - 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 Day (01-31) or "" on invalid input
  *
  * @example parseDayFromUtc("2024-03-17T14:30:45Z") // "17"
@@ -21,7 +19,7 @@ export function parseDayFromUtc(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const dateTime = utcZonedDateTime(value, options);
+        const dateTime = utcWallClock(value, options);
         return dateTime === null ? "" : dateTime.day.toString().padStart(2, "0");
     }
     catch {

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

@@ -2,12 +2,10 @@
  * 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")
+ * @param options The time zone the value is read in
  * @returns Day of week (1-7) or null on invalid input
  *
  * @example parseDayOfWeekFromUtc("2024-03-17T14:30:45Z") // 7
@@ -16,5 +14,13 @@
  * @example parseDayOfWeekFromUtc("invalid") // null
  */
 export declare function parseDayOfWeekFromUtc(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
+     * `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): number | null;

package/dist/utc/parse/parseDayOfWeekFromUtc.js

@@ -1,17 +1,15 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveReadingTimeZone } from "../../internal/resolveReadingTimeZone.js";
+import { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.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")
+ * @param options The time zone the value is read in
  * @returns Day of week (1-7) or null on invalid input
  *
  * @example parseDayOfWeekFromUtc("2024-03-17T14:30:45Z") // 7
@@ -26,11 +24,11 @@ export function parseDayOfWeekFromUtc(value, options) {
         }
         if (!isValidUtc(value))
             return null;
-        const timeZone = resolveReadingTimeZone(options?.timeZone);
-        if (timeZone === null)
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null)
             return null;
         try {
-            const dateTime = Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
+            const dateTime = frameWallClock(Temporal.Instant.from(value), frame);
             return dateTime.dayOfWeek;
         }
         catch {

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

@@ -2,12 +2,10 @@
  * 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"
@@ -15,5 +13,13 @@
  * @example parseHourFromUtc("invalid") // ""
  */
 export declare function parseHourFromUtc(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;