@northguild/gmt 1.17.0 → 1.19.0

package/dist/utc/parse/parseUnitFromUtc.js

@@ -1,34 +1,38 @@
 // 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 { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Extract a unit from a UTC datetime string.
  *
  * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
- * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
- *   `parseTimeFromUtc` does; an invalid zone returns "".
- * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
- *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
+ * - A `"week"` in late December can be week 1 of the next year, under either week numbering.
+ * - `optionsArg` must be an object or omitted: a non-object value (such as `null`) returns "".
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
  * @param unit unit to extract from the datetime
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations, timeZone (IANA, default "UTC"); a non-object value (such as `null`) is invalid
+ * @param optionsArg How weeks are numbered, and the time zone the value is read in
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromUtc("2024-03-17T14:30:45Z", "month") // "03"
  * @example parseUnitFromUtc("2024-03-17T14:30:45Z", "hours") // "14"
+ * @example parseUnitFromUtc("2024-03-17T14:30:45Z", "year") // "2024"
+ * @example parseUnitFromUtc("0005-06-01T12:30:00Z", "year") // "0005"
  * @example parseUnitFromUtc("2024-03-17T02:30:45Z", "day", { timeZone: "America/New_York" }) // "16"
  * @example parseUnitFromUtc("2024-01-01T00:00:00Z", "week") // "1"
  * @example parseUnitFromUtc("2024-12-31T12:00:00Z", "week", { weekStartsOn: "sunday" }) // "1"
  * @example parseUnitFromUtc("invalid", "month") // ""
+ * @example parseUnitFromUtc("1970-01-01T12:44:30Z", "minute", { timeZone: "-00:44:30" }) // "00" (a stored offset with seconds)
  */
 export function parseUnitFromUtc(value, unit, optionsArg) {
     try {
@@ -37,15 +41,15 @@ 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 frame = normalizeZoneFrame(optionsArg?.timeZone);
+        if (!isValidUtc(value) || weekStartsOn === null || frame === null) {
             return "";
         }
         try {
-            const dateTime = Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
+            const dateTime = frameWallClock(Temporal.Instant.from(value), frame);
             switch (resolveDateTimeUnit(unit)) {
                 case "year":
-                    return dateTime.year.toString();
+                    return isoYearString(dateTime.year);
                 case "month":
                     return dateTime.month.toString().padStart(2, "0");
                 case "week":

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,22 @@
  * @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 (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/parseWeekFromUtc.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveReadingTimeZone } from "../../internal/resolveReadingTimeZone.js";
+import { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.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,12 +31,12 @@ 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 frame = normalizeZoneFrame(optionsArg?.timeZone);
+        if (weekStartsOn === null || frame === null)
             return null;
         try {
             const instant = Temporal.Instant.from(value);
-            const dt = instant.toZonedDateTimeISO(timeZone);
+            const dt = frameWallClock(instant, frame);
             const dateStr = dt.toPlainDate().toString();
             return getWeekNumber(dateStr, weekStartsOn);
         }

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

@@ -1,19 +1,27 @@
 /**
  * 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 the year as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  * - 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 Year (YYYY) or "" on invalid input
+ * @param options The time zone the value is read in
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromUtc("2024-03-17T14:30:45Z") // "2024"
+ * @example parseYearFromUtc("0005-06-01T12:30:00Z") // "0005"
  * @example parseYearFromUtc("2025-01-01T02:00:00Z", { timeZone: "America/New_York" }) // "2024"
  * @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 (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/parseYearFromUtc.js

@@ -1,18 +1,19 @@
-import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { utcWallClock } from "../../internal/utcWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { isoYearString } from "../../internal/isoYearString.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 the year as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  * - 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 Year (YYYY) or "" on invalid input
+ * @param options The time zone the value is read in
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromUtc("2024-03-17T14:30:45Z") // "2024"
+ * @example parseYearFromUtc("0005-06-01T12:30:00Z") // "0005"
  * @example parseYearFromUtc("2025-01-01T02:00:00Z", { timeZone: "America/New_York" }) // "2024"
  * @example parseYearFromUtc("invalid") // ""
  */
@@ -21,8 +22,8 @@ export function parseYearFromUtc(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const dateTime = utcZonedDateTime(value, options);
-        return dateTime === null ? "" : dateTime.year.toString();
+        const dateTime = utcWallClock(value, options);
+        return dateTime === null ? "" : isoYearString(dateTime.year);
     }
     catch {
         // Never throws (Core Rule 3): a hostile

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

@@ -1,2 +1,4 @@
+export * from "./isValidHttpDate.js";
 export * from "./isValidUtc.js";
 export * from "./isValidUtcRange.js";
+export * from "./isValidUtcTimestamp.js";

package/dist/utc/validate/index.js

@@ -1,2 +1,4 @@
+export * from "./isValidHttpDate.js";
 export * from "./isValidUtc.js";
 export * from "./isValidUtcRange.js";
+export * from "./isValidUtcTimestamp.js";

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

@@ -0,0 +1,35 @@
+/**
+ * Return true when `value` is a real HTTP header date: the RFC 9110 §5.6.7 HTTP-date that
+ * headers like `Last-Modified`, `Date` and `Expires` carry, such as
+ * `Fri, 15 Mar 2024 14:30:00 GMT`.
+ *
+ * - True exactly when `parseHttpDate` returns a UTC string for the same value: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - **All three HTTP-date formats**, which RFC 9110 §5.6.7 says a recipient "MUST accept":
+ *   IMF-fixdate, and the obsolete rfc850-date (`Sunday, 06-Nov-94 08:49:37 GMT`) and asctime-date
+ *   (`Sun Nov  6 08:49:37 1994`). The `httpDate` pattern matches IMF-fixdate alone.
+ * - Checks the calendar as well as the shape. The pattern matches a day that does not exist:
+ *   `31 Feb`, `29 Feb 2023` and `31 Jun` are false here.
+ * - **The day name must match the date, in all three formats.** The pattern does not check it.
+ * - False for an hour above 23 and a minute above 59, which the pattern matches. False for a
+ *   second of 60: GMT rejects leap seconds.
+ * - HTTP-date is case-sensitive and fixed-width, and its zone is the literal `GMT`: a numeric
+ *   offset is false.
+ * - **An rfc850-date reads the clock.** Its two-digit year is read against the current instant
+ *   (`Temporal.Now.instant()`), as `parseHttpDate` describes, so the same string can change its
+ *   answer decades apart; if the clock cannot be read the answer is false. The other two formats
+ *   never read the clock.
+ * - False for a non-string. Read the value with `parseHttpDate`; write one with `formatHttpDate`.
+ *
+ * @param value candidate RFC 9110 HTTP-date string
+ * @returns boolean indicating validity
+ *
+ * @example isValidHttpDate("Fri, 15 Mar 2024 14:30:00 GMT") // true
+ * @example isValidHttpDate("Sun Nov  6 08:49:37 1994") // true (asctime-date; the httpDate pattern does not match it)
+ * @example isValidHttpDate("Sat, 15 Mar 2024 14:30:00 GMT") // false (15 Mar 2024 was a Friday; the httpDate pattern matches it)
+ * @example isValidHttpDate("Wed, 29 Feb 2023 14:30:00 GMT") // false (2023 has no 29 February; the httpDate pattern matches it)
+ * @example isValidHttpDate("Fri, 15 Mar 2024 24:00:00 GMT") // false (hour 24; the httpDate pattern matches it)
+ * @example isValidHttpDate("Fri, 15 Mar 2024 14:30:00 -0400") // false (not an HTTP-date)
+ * @example isValidHttpDate("not a date") // false
+ */
+export declare function isValidHttpDate(value: string): boolean;

package/dist/utc/validate/isValidHttpDate.js

@@ -0,0 +1,38 @@
+import { parseHttpDate } from "../parse/parseHttpDate.js";
+/**
+ * Return true when `value` is a real HTTP header date: the RFC 9110 §5.6.7 HTTP-date that
+ * headers like `Last-Modified`, `Date` and `Expires` carry, such as
+ * `Fri, 15 Mar 2024 14:30:00 GMT`.
+ *
+ * - True exactly when `parseHttpDate` returns a UTC string for the same value: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - **All three HTTP-date formats**, which RFC 9110 §5.6.7 says a recipient "MUST accept":
+ *   IMF-fixdate, and the obsolete rfc850-date (`Sunday, 06-Nov-94 08:49:37 GMT`) and asctime-date
+ *   (`Sun Nov  6 08:49:37 1994`). The `httpDate` pattern matches IMF-fixdate alone.
+ * - Checks the calendar as well as the shape. The pattern matches a day that does not exist:
+ *   `31 Feb`, `29 Feb 2023` and `31 Jun` are false here.
+ * - **The day name must match the date, in all three formats.** The pattern does not check it.
+ * - False for an hour above 23 and a minute above 59, which the pattern matches. False for a
+ *   second of 60: GMT rejects leap seconds.
+ * - HTTP-date is case-sensitive and fixed-width, and its zone is the literal `GMT`: a numeric
+ *   offset is false.
+ * - **An rfc850-date reads the clock.** Its two-digit year is read against the current instant
+ *   (`Temporal.Now.instant()`), as `parseHttpDate` describes, so the same string can change its
+ *   answer decades apart; if the clock cannot be read the answer is false. The other two formats
+ *   never read the clock.
+ * - False for a non-string. Read the value with `parseHttpDate`; write one with `formatHttpDate`.
+ *
+ * @param value candidate RFC 9110 HTTP-date string
+ * @returns boolean indicating validity
+ *
+ * @example isValidHttpDate("Fri, 15 Mar 2024 14:30:00 GMT") // true
+ * @example isValidHttpDate("Sun Nov  6 08:49:37 1994") // true (asctime-date; the httpDate pattern does not match it)
+ * @example isValidHttpDate("Sat, 15 Mar 2024 14:30:00 GMT") // false (15 Mar 2024 was a Friday; the httpDate pattern matches it)
+ * @example isValidHttpDate("Wed, 29 Feb 2023 14:30:00 GMT") // false (2023 has no 29 February; the httpDate pattern matches it)
+ * @example isValidHttpDate("Fri, 15 Mar 2024 24:00:00 GMT") // false (hour 24; the httpDate pattern matches it)
+ * @example isValidHttpDate("Fri, 15 Mar 2024 14:30:00 -0400") // false (not an HTTP-date)
+ * @example isValidHttpDate("not a date") // false
+ */
+export function isValidHttpDate(value) {
+    return parseHttpDate(value) !== "";
+}

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

@@ -6,6 +6,10 @@
  * - Reads RFC 9557 annotations as `Temporal.Instant.from` does: elective ones (`[foo=bar]`), a
  *   time zone annotation and a calendar annotation are ignored (an instant has neither), and an
  *   unknown critical one (`[!foo=bar]`) is rejected.
+ * - Accepts four forms beyond the timestamp shape `YYYY-MM-DDTHH:MM:SS[.f]Z`: a time without
+ *   seconds, a comma before the fraction, an expanded `±YYYYYY` year and RFC 9557 annotations.
+ *   For the plain RFC 3339 spelling that readers other than Temporal expect, use
+ *   `isValidUtcTimestamp`, which is false for all four.
  * - Rejects leap seconds (e.g., "2024-12-31T23:59:60Z").
  * - Uses Temporal.Instant.from for validation.
  * - Requires a time component — date-only strings ("2024-01-01Z") are rejected.

package/dist/utc/validate/isValidUtc.js

@@ -10,6 +10,10 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  * - Reads RFC 9557 annotations as `Temporal.Instant.from` does: elective ones (`[foo=bar]`), a
  *   time zone annotation and a calendar annotation are ignored (an instant has neither), and an
  *   unknown critical one (`[!foo=bar]`) is rejected.
+ * - Accepts four forms beyond the timestamp shape `YYYY-MM-DDTHH:MM:SS[.f]Z`: a time without
+ *   seconds, a comma before the fraction, an expanded `±YYYYYY` year and RFC 9557 annotations.
+ *   For the plain RFC 3339 spelling that readers other than Temporal expect, use
+ *   `isValidUtcTimestamp`, which is false for all four.
  * - Rejects leap seconds (e.g., "2024-12-31T23:59:60Z").
  * - Uses Temporal.Instant.from for validation.
  * - Requires a time component — date-only strings ("2024-01-01Z") are rejected.

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

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

@@ -0,0 +1,43 @@
+/**
+ * Return true when `value` is a real UTC instant written as `YYYY-MM-DDTHH:MM:SS[.f]Z` and
+ * nothing else: a narrower check than `isValidUtc`.
+ *
+ * - The shape is one spelling of the RFC 3339 §5.6 `date-time`: a four-digit year, `0000` to
+ *   `9999` (`date-fullyear = 4DIGIT`), an upper-case `T`, a time with seconds, an optional
+ *   fraction of one to nine digits after a dot (`time-secfrac = "." 1*DIGIT`; GMT stops at nine
+ *   because Temporal keeps nanoseconds), and an upper-case `Z` with nothing after it.
+ * - Use it for a string headed for storage, or for a reader that is not Temporal: the shape is
+ *   plain RFC 3339, and the one `Temporal.Instant.prototype.toString()`, called with no options,
+ *   writes for years `0000` to `9999`.
+ * - Use `isValidUtc` when Temporal is the only reader. It also accepts a time without seconds, a
+ *   comma before the fraction, an expanded `±YYYYYY` year and RFC 9557 annotations; all four are
+ *   false here.
+ * - A subset of `isValidUtc`: every string that is true here is true there. The instant is
+ *   checked as well as the shape, so a day that does not exist is false.
+ * - False for the other spellings §5.6 allows: a lower-case `t` or `z`, a space for `T` (its
+ *   NOTE), and a numeric offset, `+00:00` included. `isValidRfc3339DateTime` checks the whole
+ *   grammar, with the same two GMT limits.
+ * - False for a leap second (`:60`), although §5.6 `time-second` admits it: GMT rejects leap
+ *   seconds because Temporal would read one as `:59`.
+ * - Not one canonical spelling: `12:00:00Z` and `12:00:00.000Z` are one instant and both are
+ *   true. A reader may still refuse or round a string that is true here: PostgreSQL has no year
+ *   `0000` and keeps microseconds. See `toPgMicroseconds` and `precision/`.
+ * - False for a non-string.
+ *
+ * @param value candidate UTC timestamp string
+ * @returns true when `value` is a real UTC instant in this shape, or false on invalid input
+ *
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00Z") // true
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00.123456789Z") // true (nine fraction digits)
+ * @example isValidUtcTimestamp("0000-01-01T00:00:00Z") // true (year 0000)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00Z[Europe/Paris]") // false (RFC 9557 annotation; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00,5Z") // false (comma before the fraction; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("-005000-01-01T00:00:00Z") // false (expanded year; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06T12:00Z") // false (no seconds; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06t12:00:00z") // false (lower-case t and z)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00+00:00") // false (a numeric offset, not Z)
+ * @example isValidUtcTimestamp("2026-02-30T00:00:00Z") // false (February has no 30th; the rfc3339DateTime pattern matches it)
+ * @example isValidUtcTimestamp("2016-12-31T23:59:60Z") // false (leap second)
+ * @example isValidUtcTimestamp("not a date") // false
+ */
+export declare function isValidUtcTimestamp(value: string): boolean;

package/dist/utc/validate/isValidUtcTimestamp.js

@@ -0,0 +1,48 @@
+import { rfc3339DateTime } from "../../regex/rfc-3339.js";
+import { isValidUtc } from "./isValidUtc.js";
+/**
+ * Return true when `value` is a real UTC instant written as `YYYY-MM-DDTHH:MM:SS[.f]Z` and
+ * nothing else: a narrower check than `isValidUtc`.
+ *
+ * - The shape is one spelling of the RFC 3339 §5.6 `date-time`: a four-digit year, `0000` to
+ *   `9999` (`date-fullyear = 4DIGIT`), an upper-case `T`, a time with seconds, an optional
+ *   fraction of one to nine digits after a dot (`time-secfrac = "." 1*DIGIT`; GMT stops at nine
+ *   because Temporal keeps nanoseconds), and an upper-case `Z` with nothing after it.
+ * - Use it for a string headed for storage, or for a reader that is not Temporal: the shape is
+ *   plain RFC 3339, and the one `Temporal.Instant.prototype.toString()`, called with no options,
+ *   writes for years `0000` to `9999`.
+ * - Use `isValidUtc` when Temporal is the only reader. It also accepts a time without seconds, a
+ *   comma before the fraction, an expanded `±YYYYYY` year and RFC 9557 annotations; all four are
+ *   false here.
+ * - A subset of `isValidUtc`: every string that is true here is true there. The instant is
+ *   checked as well as the shape, so a day that does not exist is false.
+ * - False for the other spellings §5.6 allows: a lower-case `t` or `z`, a space for `T` (its
+ *   NOTE), and a numeric offset, `+00:00` included. `isValidRfc3339DateTime` checks the whole
+ *   grammar, with the same two GMT limits.
+ * - False for a leap second (`:60`), although §5.6 `time-second` admits it: GMT rejects leap
+ *   seconds because Temporal would read one as `:59`.
+ * - Not one canonical spelling: `12:00:00Z` and `12:00:00.000Z` are one instant and both are
+ *   true. A reader may still refuse or round a string that is true here: PostgreSQL has no year
+ *   `0000` and keeps microseconds. See `toPgMicroseconds` and `precision/`.
+ * - False for a non-string.
+ *
+ * @param value candidate UTC timestamp string
+ * @returns true when `value` is a real UTC instant in this shape, or false on invalid input
+ *
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00Z") // true
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00.123456789Z") // true (nine fraction digits)
+ * @example isValidUtcTimestamp("0000-01-01T00:00:00Z") // true (year 0000)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00Z[Europe/Paris]") // false (RFC 9557 annotation; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00,5Z") // false (comma before the fraction; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("-005000-01-01T00:00:00Z") // false (expanded year; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06T12:00Z") // false (no seconds; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06t12:00:00z") // false (lower-case t and z)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00+00:00") // false (a numeric offset, not Z)
+ * @example isValidUtcTimestamp("2026-02-30T00:00:00Z") // false (February has no 30th; the rfc3339DateTime pattern matches it)
+ * @example isValidUtcTimestamp("2016-12-31T23:59:60Z") // false (leap second)
+ * @example isValidUtcTimestamp("not a date") // false
+ */
+export function isValidUtcTimestamp(value) {
+    // `isValidUtc` goes first: it stops a non-string before the pattern would read it as text.
+    return isValidUtc(value) && rfc3339DateTime.test(value);
+}

package/dist/zoned/calculate/addZoned.d.ts

@@ -16,13 +16,9 @@ import type { DateTimeDurationUnit, Disambiguation, Overflow } from "../../types
  *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
  * - Follows Temporal's AddZonedDateTime: the date portion of the duration (years, months, weeks,
  *   days) moves the wall-clock date, then the time portion (hours and smaller) is added in exact
- *   time. `disambiguation` ("compatible" (default), "earlier", "later", or "reject" (returns
- *   "")) applies ONLY to the intermediate wall-clock date-time after the date portion, exactly as
- *   Temporal's GetEpochNanosecondsFor resolves it: in a fall-back (DST-end) overlap "compatible"
- *   and "earlier" take the earlier instant and "later" the later one; in a spring-forward
- *   (DST-start) gap "compatible" and "later" move the wall clock forward by the gap length and
- *   "earlier" back by it; "reject" returns "" for both. It never re-resolves the exact-time
- *   result, so a time-only duration ignores it.
+ *   time. `disambiguation` applies ONLY to the intermediate wall-clock date-time after the date
+ *   portion, exactly as Temporal's GetEpochNanosecondsFor resolves it. It never re-resolves the
+ *   exact-time result.
  * - Compatibility: before 1.16.0 a date portion landing in a spring-forward gap was always moved
  *   forward, whatever `disambiguation` said, so "earlier" matched "compatible" and "reject" did not
  *   fail. Pass "compatible" (or omit it) to keep the forward result.
@@ -33,13 +29,11 @@ import type { DateTimeDurationUnit, Disambiguation, Overflow } from "../../types
  * - There is no `offset` option (removed in 1.16.0): the intermediate wall clock is resolved from
  *   a plain date-time, which has no UTC offset for it to act on (Temporal
  *   `PlainDateTime#toZonedDateTime` reads only `disambiguation`).
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
  * - Returns "" for invalid input.
  *
  * @param value ISO 8601 zoned datetime string, optionally calendar-annotated
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), overflow ("constrain" | "reject")
+ * @param optionsArg optional settings for resolving a DST gap or overlap and an out-of-range date
  * @returns zoned ISO 8601 string on success, or "" on invalid input
  *
  * @example addZoned("2024-02-29T14:30:45.123-05:00[America/New_York]", { days: 1 }) // "2024-03-01T14:30:45.123-05:00[America/New_York]"
@@ -58,6 +52,22 @@ import type { DateTimeDurationUnit, Disambiguation, Overflow } from "../../types
  * @example addZoned("2024-01-31T12:00:00-05:00[America/New_York]", { months: 1 }, { overflow: "reject" }) // ""
  */
 export declare function addZoned(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, optionsArg?: {
+    /**
+     * How the intermediate wall-clock date-time, reached after the date portion of the duration is
+     * applied, resolves when it falls in a DST gap or overlap. In a fall-back overlap
+     * `"compatible"` and `"earlier"` take the earlier instant and `"later"` the later one; in a
+     * spring-forward gap `"compatible"` and `"later"` move the wall clock forward by the gap length
+     * and `"earlier"` back by it. `"reject"` returns `""` for both, and a time-only duration
+     * ignores the option.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
     disambiguation?: Disambiguation;
+    /**
+     * What happens when the result names a day its month does not have, such as adding 1 month to
+     * 31 January. `"constrain"` clamps to the last valid day; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;