@northguild/gmt 1.14.2 → 1.16.0

package/dist/plain/validate/isLeapSecond.js

@@ -1,19 +1,40 @@
 import { leapSecond } from "../../regex/leap-second.js";
 /**
- * Return true if the provided string is a valid ISO 8601 leap second datetime.
+ * Return true if the provided ISO 8601 date-time or time string has a second-60 field.
  *
- * - Validates leap second format using regex: "YYYY-MM-DDT23:59:60Z" or "YYYY-MM-DDT23:59:60+00:00".
+ * - This is a syntactic test of the seconds field, the spelling Temporal would silently clamp to
+ *   `:59`. It does not check the IERS leap-second list: a real leap second exists only at
+ *   23:59:60 UTC at the end of a month in which one was inserted (RFC 3339 §5.7), so
+ *   `"2024-12-31T23:59:60Z"` (no leap second that day, IERS Bulletin C 68) and
+ *   `"2024-06-15T12:34:60Z"` both return true.
+ * - Matches a seconds field of `60` with any date, time of day or offset, or none, for example
+ *   "YYYY-MM-DDT23:59:60Z", "YYYY-MM-DDT23:59:60+00:00", "YYYY-MM-DDT23:59:60" or "23:59:60".
  * - Accepts optional fractional seconds.
+ * - Accepts every spelling Temporal's grammar parses: a `T`, `t` or space separator, and
+ *   extended or basic digits, a bare time with or without a `T` designator, and a designator,
+ *   annotation or nothing after the second. Temporal silently clamps each of them to `:59`, so
+ *   each is a leap second GMT has to catch. A `[key=value]` annotation value is never read as a time.
+ * - Compatibility: earlier releases recognised only an uppercase `T` with extended digits. To
+ *   keep that narrower test, match `/T\d{2}:\d{2}:60(?:[.,]\d+)?[-+Zz[]/` yourself.
  *
- * @param value ISO datetime string
- * @returns boolean indicating whether the input string is a valid leap second datetime
+ * @param value ISO date-time or time string
+ * @returns true when the string has a second-60 field, otherwise false
  *
- * @example isLeapSecond("2024-12-31T23:59:60Z") // true
- * @example isLeapSecond("2024-12-31T23:59:60.123Z") // true
- * @example isLeapSecond("2024-12-31T23:59:60+00:00") // true
- * @example isLeapSecond("2024-12-31T23:59:60.123+00:00") // true
- * @example isLeapSecond("2024-12-31T23:59:59Z") // false
+ * @example isLeapSecond("2016-12-31T23:59:60Z") // true
+ * @example isLeapSecond("2016-12-31T23:59:60.123Z") // true
+ * @example isLeapSecond("2016-12-31T23:59:60+00:00") // true
+ * @example isLeapSecond("2016-12-31T23:59:60.123+00:00") // true
+ * @example isLeapSecond("2016-12-31t23:59:60Z") // true (lowercase t)
+ * @example isLeapSecond("20161231 235960Z") // true (space separator, basic format)
+ * @example isLeapSecond("2016-12-31T23:59:60") // true (no designator; PlainDateTime clamps it)
+ * @example isLeapSecond("23:59:60") // true (a time; PlainTime clamps it)
+ * @example isLeapSecond("2016-12-31T23:59:59Z") // false
+ * @example isLeapSecond("2024-06-15T12:34:60Z") // true (syntactic: no leap second can occur here)
+ * @example /T\d{2}:\d{2}:60(?:[.,]\d+)?[-+Zz[]/.test("2016-12-31t23:59:60Z") // false (the earlier uppercase-T-only test)
  */
 export function isLeapSecond(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
     return leapSecond.test(value);
 }

package/dist/plain/validate/isLeapYear.d.ts

@@ -2,7 +2,11 @@
  * Return true when the given PlainDate falls in a leap year.
  *
  * - A leap year is divisible by 4, except for century years which must be divisible by 400.
- * - Returns false for invalid input strings.
+ * - Returns false for invalid input strings, including every shape `isValidDate` rejects: a
+ *   date-time, zoned, basic-format or leap-second string, or a non-ISO calendar annotation. The
+ *   annotations Temporal ignores are accepted (`"2024-06-15[u-ca=iso8601]"` → true).
+ * - Compatibility: earlier releases read those shapes loosely (`"2024-03-15T10:00"` → `true`).
+ *   Pass the date part alone, or use `Temporal.PlainDate.from(value).inLeapYear`.
  *
  * @param value ISO PlainDate string
  * @returns boolean indicating whether the date is in a leap year
@@ -10,5 +14,7 @@
  * @example isLeapYear("2024-03-15") // true
  * @example isLeapYear("2023-03-15") // false
  * @example isLeapYear("invalid") // false
+ * @example isLeapYear("2024-03-15T10:00") // false (a date-time, not a PlainDate)
+ * @example isLeapYear("2024-03-15T10:00".slice(0, 10)) // true (the date part)
  */
 export declare function isLeapYear(value: string): boolean;

package/dist/plain/validate/isLeapYear.js

@@ -1,9 +1,14 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "./isValidDate.js";
 /**
  * Return true when the given PlainDate falls in a leap year.
  *
  * - A leap year is divisible by 4, except for century years which must be divisible by 400.
- * - Returns false for invalid input strings.
+ * - Returns false for invalid input strings, including every shape `isValidDate` rejects: a
+ *   date-time, zoned, basic-format or leap-second string, or a non-ISO calendar annotation. The
+ *   annotations Temporal ignores are accepted (`"2024-06-15[u-ca=iso8601]"` → true).
+ * - Compatibility: earlier releases read those shapes loosely (`"2024-03-15T10:00"` → `true`).
+ *   Pass the date part alone, or use `Temporal.PlainDate.from(value).inLeapYear`.
  *
  * @param value ISO PlainDate string
  * @returns boolean indicating whether the date is in a leap year
@@ -11,8 +16,12 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example isLeapYear("2024-03-15") // true
  * @example isLeapYear("2023-03-15") // false
  * @example isLeapYear("invalid") // false
+ * @example isLeapYear("2024-03-15T10:00") // false (a date-time, not a PlainDate)
+ * @example isLeapYear("2024-03-15T10:00".slice(0, 10)) // true (the date part)
  */
 export function isLeapYear(value) {
+    if (!isValidDate(value))
+        return false;
     try {
         const date = Temporal.PlainDate.from(value);
         return date.inLeapYear;

package/dist/plain/validate/isValidCalendarDate.d.ts

@@ -1,17 +1,48 @@
 /**
- * Return true if `value` is a valid GMT PlainDate string: a plain ISO date
- * ("2024-10-03") or a calendar-annotated date with calendar-native fields
- * ("5785-01-01[u-ca=hebrew]"), as produced by `convertDateToCalendar`.
+ * Return true if `value` is a valid GMT PlainDate string: a bare ISO date ("2024-10-03") or an
+ * RFC 9557 calendar-annotated date ("2024-10-03[u-ca=hebrew]"), as `Temporal.PlainDate#toString()`
+ * and `convertDateToCalendar` write it.
  *
- * - Delegates all field-range and calendar-identifier checking to
- *   `Temporal.PlainDate.from` (via `parseCalendarDateValue`).
+ * - The digits are the ISO date whatever the calendar, so the ISO date must be valid and within
+ *   Temporal's range (-271821-04-19 to +275760-09-13). The year is four digits or a sign and six.
+ * - A `[u-ca=<id>]` annotation, optionally critical (`[!u-ca=hebrew]`). Temporal's
+ *   `CanonicalizeCalendar` validates the id, folding case and aliases (`[u-ca=HEBREW]`,
+ *   `[u-ca=ethiopic-amete-alem]`), and the calendar must be one GMT supports (`CalendarSystem`);
+ *   `chinese`, `dangi`, `islamic` and `islamic-rgsa` return false.
+ * - The annotations follow Temporal's ISO grammar, as `Temporal.PlainDate.from` reads them: a time
+ *   zone annotation and elective unknown annotations (`[foo=bar]`) are ignored and the first
+ *   `u-ca` annotation names the calendar; an unknown critical annotation (`[!foo=bar]`) or a
+ *   second `u-ca` annotation when either is critical returns false.
+ * - A date-time is valid and names its date, as `Temporal.PlainDate.from` reads it
+ *   (`"2024-10-03T14:30[u-ca=hebrew]"` is 2024-10-03 in Hebrew): the time is dropped.
+ * - The part before the first `[` must match GMT's strict extended shape, as `isValidDate` and
+ *   `isValidDateTime` require: basic format (`20241003`), a space or lower-case `t` separator, a
+ *   UTC offset or designator and a leap second (second `60`) return false, although
+ *   `Temporal.PlainDate.from` reads all but the designator.
+ * - Returns false for non-strings or empty strings.
+ *
+ * Compatibility: since 1.16.0 the string is RFC 9557, and a date-time is read as its date (earlier
+ * releases returned false). Earlier releases accepted calendar-native
+ * digits, `;era=` and the ids `gregorian`, `taiwan`, `islamic-tabular` and `ethiopic-amete-alem`;
+ * a `;era=` string or a six-digit unsigned year now returns false, and any other such string is
+ * read as the ISO date its digits spell.
  *
  * @param value ISO PlainDate string, optionally calendar-annotated
  * @returns boolean indicating validity
  *
  * @example isValidCalendarDate("2024-10-03") // true
- * @example isValidCalendarDate("5785-01-01[u-ca=hebrew]") // true
+ * @example isValidCalendarDate("2024-10-03[u-ca=hebrew]") // true
+ * @example isValidCalendarDate("+275760-09-13[u-ca=roc]") // true
+ * @example isValidCalendarDate("2024-10-03[!u-ca=japanese]") // true (critical flag)
+ * @example isValidCalendarDate("2024-10-03[Asia/Tokyo][u-ca=hebrew]") // true (the time zone annotation is ignored)
+ * @example isValidCalendarDate("2024-10-03T14:30:00[u-ca=hebrew]") // true (a date-time names its date)
+ * @example isValidCalendarDate("2024-10-03T14:30:00Z[u-ca=hebrew]") // false (UTC designator on a Plain type)
+ * @example isValidCalendarDate("20241003[u-ca=hebrew]") // false (basic format, as isValidDate)
+ * @example isValidCalendarDate("2024-10-03T14:30+01:00[u-ca=hebrew]") // false (UTC offset, as isValidDateTime)
+ * @example isValidCalendarDate("2024-10-03[!foo=bar][u-ca=hebrew]") // false (unknown critical annotation)
  * @example isValidCalendarDate("2024-10-03[u-ca=martian]") // false (unknown calendar identifier)
+ * @example isValidCalendarDate("2024-10-03[u-ca=chinese]") // false (not supported by GMT)
+ * @example isValidCalendarDate("0006-10-03[u-ca=japanese;era=reiwa]") // false (not RFC 9557)
  * @example isValidCalendarDate("invalid") // false
  */
 export declare function isValidCalendarDate(value: string): boolean;

package/dist/plain/validate/isValidCalendarDate.js

@@ -1,18 +1,49 @@
 import { parseCalendarDateValue } from "../../internal/index.js";
 /**
- * Return true if `value` is a valid GMT PlainDate string: a plain ISO date
- * ("2024-10-03") or a calendar-annotated date with calendar-native fields
- * ("5785-01-01[u-ca=hebrew]"), as produced by `convertDateToCalendar`.
+ * Return true if `value` is a valid GMT PlainDate string: a bare ISO date ("2024-10-03") or an
+ * RFC 9557 calendar-annotated date ("2024-10-03[u-ca=hebrew]"), as `Temporal.PlainDate#toString()`
+ * and `convertDateToCalendar` write it.
  *
- * - Delegates all field-range and calendar-identifier checking to
- *   `Temporal.PlainDate.from` (via `parseCalendarDateValue`).
+ * - The digits are the ISO date whatever the calendar, so the ISO date must be valid and within
+ *   Temporal's range (-271821-04-19 to +275760-09-13). The year is four digits or a sign and six.
+ * - A `[u-ca=<id>]` annotation, optionally critical (`[!u-ca=hebrew]`). Temporal's
+ *   `CanonicalizeCalendar` validates the id, folding case and aliases (`[u-ca=HEBREW]`,
+ *   `[u-ca=ethiopic-amete-alem]`), and the calendar must be one GMT supports (`CalendarSystem`);
+ *   `chinese`, `dangi`, `islamic` and `islamic-rgsa` return false.
+ * - The annotations follow Temporal's ISO grammar, as `Temporal.PlainDate.from` reads them: a time
+ *   zone annotation and elective unknown annotations (`[foo=bar]`) are ignored and the first
+ *   `u-ca` annotation names the calendar; an unknown critical annotation (`[!foo=bar]`) or a
+ *   second `u-ca` annotation when either is critical returns false.
+ * - A date-time is valid and names its date, as `Temporal.PlainDate.from` reads it
+ *   (`"2024-10-03T14:30[u-ca=hebrew]"` is 2024-10-03 in Hebrew): the time is dropped.
+ * - The part before the first `[` must match GMT's strict extended shape, as `isValidDate` and
+ *   `isValidDateTime` require: basic format (`20241003`), a space or lower-case `t` separator, a
+ *   UTC offset or designator and a leap second (second `60`) return false, although
+ *   `Temporal.PlainDate.from` reads all but the designator.
+ * - Returns false for non-strings or empty strings.
+ *
+ * Compatibility: since 1.16.0 the string is RFC 9557, and a date-time is read as its date (earlier
+ * releases returned false). Earlier releases accepted calendar-native
+ * digits, `;era=` and the ids `gregorian`, `taiwan`, `islamic-tabular` and `ethiopic-amete-alem`;
+ * a `;era=` string or a six-digit unsigned year now returns false, and any other such string is
+ * read as the ISO date its digits spell.
  *
  * @param value ISO PlainDate string, optionally calendar-annotated
  * @returns boolean indicating validity
  *
  * @example isValidCalendarDate("2024-10-03") // true
- * @example isValidCalendarDate("5785-01-01[u-ca=hebrew]") // true
+ * @example isValidCalendarDate("2024-10-03[u-ca=hebrew]") // true
+ * @example isValidCalendarDate("+275760-09-13[u-ca=roc]") // true
+ * @example isValidCalendarDate("2024-10-03[!u-ca=japanese]") // true (critical flag)
+ * @example isValidCalendarDate("2024-10-03[Asia/Tokyo][u-ca=hebrew]") // true (the time zone annotation is ignored)
+ * @example isValidCalendarDate("2024-10-03T14:30:00[u-ca=hebrew]") // true (a date-time names its date)
+ * @example isValidCalendarDate("2024-10-03T14:30:00Z[u-ca=hebrew]") // false (UTC designator on a Plain type)
+ * @example isValidCalendarDate("20241003[u-ca=hebrew]") // false (basic format, as isValidDate)
+ * @example isValidCalendarDate("2024-10-03T14:30+01:00[u-ca=hebrew]") // false (UTC offset, as isValidDateTime)
+ * @example isValidCalendarDate("2024-10-03[!foo=bar][u-ca=hebrew]") // false (unknown critical annotation)
  * @example isValidCalendarDate("2024-10-03[u-ca=martian]") // false (unknown calendar identifier)
+ * @example isValidCalendarDate("2024-10-03[u-ca=chinese]") // false (not supported by GMT)
+ * @example isValidCalendarDate("0006-10-03[u-ca=japanese;era=reiwa]") // false (not RFC 9557)
  * @example isValidCalendarDate("invalid") // false
  */
 export function isValidCalendarDate(value) {

package/dist/plain/validate/isValidDate.d.ts

@@ -1,7 +1,11 @@
 /**
  * Return true if `value` is a valid ISO PlainDate string.
  *
- * - Uses regex to check format before parsing.
+ * - The part before the first annotation must match `plainDate` (a date, not a date-time).
+ * - Reads RFC 9557 annotations as `Temporal.PlainDate.from` does: elective ones (`[foo=bar]`)
+ *   and a time zone annotation are ignored, and an unknown critical one (`[!foo=bar]`) is
+ *   rejected. The calendar must be ISO (`[u-ca=iso8601]` is accepted); a non-ISO calendar is
+ *   `isValidCalendarDate`'s input.
  * - Rejects leap seconds (e.g., "2024-12-31T23:59:60").
  * - Rejects invalid dates (e.g., "2024-02-30").
  *
@@ -10,6 +14,10 @@
  *
  * @example isValidDate("2024-03-10") // true
  * @example isValidDate("2024-02-30") // false
+ * @example isValidDate("2024-03-10[u-ca=iso8601]") // true
+ * @example isValidDate("2024-03-10[foo=bar]") // true (elective annotation ignored)
+ * @example isValidDate("2024-03-10[!foo=bar]") // false (unknown critical annotation)
+ * @example isValidDate("2024-03-10[u-ca=hebrew]") // false (use isValidCalendarDate)
  * @example isValidDate("invalid") // false
  * @example isValidDate("2024-12-31T23:59:60") // false (leap second - not a valid date)
  */

package/dist/plain/validate/isValidDate.js

@@ -1,10 +1,15 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isoStringBody } from "../../internal/isoStringBody.js";
 import { plainDate } from "../../regex/index.js";
 import { isLeapSecond } from "./isLeapSecond.js";
 /**
  * Return true if `value` is a valid ISO PlainDate string.
  *
- * - Uses regex to check format before parsing.
+ * - The part before the first annotation must match `plainDate` (a date, not a date-time).
+ * - Reads RFC 9557 annotations as `Temporal.PlainDate.from` does: elective ones (`[foo=bar]`)
+ *   and a time zone annotation are ignored, and an unknown critical one (`[!foo=bar]`) is
+ *   rejected. The calendar must be ISO (`[u-ca=iso8601]` is accepted); a non-ISO calendar is
+ *   `isValidCalendarDate`'s input.
  * - Rejects leap seconds (e.g., "2024-12-31T23:59:60").
  * - Rejects invalid dates (e.g., "2024-02-30").
  *
@@ -13,19 +18,23 @@ import { isLeapSecond } from "./isLeapSecond.js";
  *
  * @example isValidDate("2024-03-10") // true
  * @example isValidDate("2024-02-30") // false
+ * @example isValidDate("2024-03-10[u-ca=iso8601]") // true
+ * @example isValidDate("2024-03-10[foo=bar]") // true (elective annotation ignored)
+ * @example isValidDate("2024-03-10[!foo=bar]") // false (unknown critical annotation)
+ * @example isValidDate("2024-03-10[u-ca=hebrew]") // false (use isValidCalendarDate)
  * @example isValidDate("invalid") // false
  * @example isValidDate("2024-12-31T23:59:60") // false (leap second - not a valid date)
  */
 export function isValidDate(value) {
-    if (isLeapSecond(value)) {
+    const body = isoStringBody(value);
+    if (isLeapSecond(body)) {
         return false;
     }
-    if (!plainDate.test(value)) {
+    if (!plainDate.test(body)) {
         return false;
     }
     try {
-        Temporal.PlainDate.from(value);
-        return true;
+        return Temporal.PlainDate.from(value).calendarId === "iso8601";
     }
     catch {
         return false;

package/dist/plain/validate/isValidDateRange.d.ts

@@ -1,4 +1,11 @@
-interface IsValidDateRangeProps {
+/**
+ * The argument object of `isValidDateRange`.
+ *
+ * @example
+ * import { IsValidDateRangeProps } from "@northguild/gmt/plain";
+ * const range: IsValidDateRangeProps = { value1: "2024-02-28", value2: "2024-02-29" };
+ */
+export interface IsValidDateRangeProps {
     value1: string;
     value2: string;
     options?: {
@@ -8,7 +15,8 @@ interface IsValidDateRangeProps {
 /**
  * Return whether `value1` is before `value2`.
  *
- * - Validates both dates using regex and Temporal.PlainDate.from().
+ * - Validates both dates with `isValidDate`, so each endpoint's RFC 9557 annotations are read as
+ *   `Temporal.PlainDate.from` reads them (an elective `[foo=bar]` or `[u-ca=iso8601]` is ignored).
  * - Rejects leap seconds in either date.
  * - When `options.allowEqual` is true, equality is considered valid as well.
  *
@@ -22,5 +30,4 @@ interface IsValidDateRangeProps {
  * @example isValidDateRange({ value1: "2024-02-29", value2: "2024-02-29" }) // false
  * @example isValidDateRange({ value1: "2024-02-29", value2: "2024-02-29", options: { allowEqual: true } }) // true
  */
-export declare function isValidDateRange({ value1, value2, options, }: IsValidDateRangeProps): boolean;
-export {};
+export declare function isValidDateRange(props: IsValidDateRangeProps): boolean;

package/dist/plain/validate/isValidDateRange.js

@@ -1,10 +1,11 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { plainDate } from "../../regex/index.js";
-import { isLeapSecond } from "./isLeapSecond.js";
+import { isValidDate } from "./isValidDate.js";
+import { isObject, isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return whether `value1` is before `value2`.
  *
- * - Validates both dates using regex and Temporal.PlainDate.from().
+ * - Validates both dates with `isValidDate`, so each endpoint's RFC 9557 annotations are read as
+ *   `Temporal.PlainDate.from` reads them (an elective `[foo=bar]` or `[u-ca=iso8601]` is ignored).
  * - Rejects leap seconds in either date.
  * - When `options.allowEqual` is true, equality is considered valid as well.
  *
@@ -18,30 +19,39 @@ import { isLeapSecond } from "./isLeapSecond.js";
  * @example isValidDateRange({ value1: "2024-02-29", value2: "2024-02-29" }) // false
  * @example isValidDateRange({ value1: "2024-02-29", value2: "2024-02-29", options: { allowEqual: true } }) // true
  */
-export function isValidDateRange({ value1, value2, options, }) {
-    if (isLeapSecond(value1) || isLeapSecond(value2)) {
-        return false;
-    }
-    if (!plainDate.test(value1) || !plainDate.test(value2)) {
-        return false;
-    }
+export function isValidDateRange(props) {
     try {
-        const date1 = Temporal.PlainDate.from(value1);
-        const date2 = Temporal.PlainDate.from(value2);
-        const isLessThan = date1.year < date2.year ||
-            (date1.year === date2.year && date1.month < date2.month) ||
-            (date1.year === date2.year &&
+        if (!isObject(props))
+            return false;
+        const { value1, value2, options } = props;
+        if (!isOptionsArgument(options))
+            return false;
+        if (!isValidDate(value1) || !isValidDate(value2)) {
+            return false;
+        }
+        try {
+            const date1 = Temporal.PlainDate.from(value1);
+            const date2 = Temporal.PlainDate.from(value2);
+            const isLessThan = date1.year < date2.year ||
+                (date1.year === date2.year && date1.month < date2.month) ||
+                (date1.year === date2.year &&
+                    date1.month === date2.month &&
+                    date1.day < date2.day);
+            const isEqual = date1.year === date2.year &&
                 date1.month === date2.month &&
-                date1.day < date2.day);
-        const isEqual = date1.year === date2.year &&
-            date1.month === date2.month &&
-            date1.day === date2.day;
-        if (options?.allowEqual) {
-            return isLessThan || isEqual;
+                date1.day === date2.day;
+            if (options?.allowEqual) {
+                return isLessThan || isEqual;
+            }
+            return isLessThan;
+        }
+        catch {
+            return false;
         }
-        return isLessThan;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/plain/validate/isValidDateTime.d.ts

@@ -1,7 +1,10 @@
 /**
  * Return true when `value` is a valid PlainDateTime string.
  *
- * - Uses regex to check format before parsing.
+ * - The part before the first annotation must match `plainDateTime`.
+ * - Reads RFC 9557 annotations as `Temporal.PlainDateTime.from` does: elective ones
+ *   (`[foo=bar]`) and a time zone annotation are ignored, and an unknown critical one
+ *   (`[!foo=bar]`) is rejected. The calendar must be ISO (`[u-ca=iso8601]` is accepted).
  * - Rejects leap seconds (e.g., "2024-02-29T23:59:60").
  * - Rejects invalid dates (e.g., "2024-02-30") and invalid times (e.g., "2024-02-29T24:00:00").
  *
@@ -10,6 +13,9 @@
  *
  * @example isValidDateTime("2024-02-29T12:34:56") // true
  * @example isValidDateTime("2024-02-30T12:34:56") // false (invalid date)
+ * @example isValidDateTime("2024-02-29T12:34:56[America/New_York]") // true (time zone annotation ignored)
+ * @example isValidDateTime("2024-02-29T12:34:56[!foo=bar]") // false (unknown critical annotation)
+ * @example isValidDateTime("2024-02-29T12:34:56[u-ca=hebrew]") // false (non-ISO calendar)
  * @example isValidDateTime("2024-02-29T24:00:00") // false (invalid time)
  * @example isValidDateTime("2024-02-29T23:59:60") // false (leap second)
  */

package/dist/plain/validate/isValidDateTime.js

@@ -1,10 +1,14 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isoStringBody } from "../../internal/isoStringBody.js";
 import { plainDateTime } from "../../regex/index.js";
 import { isLeapSecond } from "./isLeapSecond.js";
 /**
  * Return true when `value` is a valid PlainDateTime string.
  *
- * - Uses regex to check format before parsing.
+ * - The part before the first annotation must match `plainDateTime`.
+ * - Reads RFC 9557 annotations as `Temporal.PlainDateTime.from` does: elective ones
+ *   (`[foo=bar]`) and a time zone annotation are ignored, and an unknown critical one
+ *   (`[!foo=bar]`) is rejected. The calendar must be ISO (`[u-ca=iso8601]` is accepted).
  * - Rejects leap seconds (e.g., "2024-02-29T23:59:60").
  * - Rejects invalid dates (e.g., "2024-02-30") and invalid times (e.g., "2024-02-29T24:00:00").
  *
@@ -13,19 +17,22 @@ import { isLeapSecond } from "./isLeapSecond.js";
  *
  * @example isValidDateTime("2024-02-29T12:34:56") // true
  * @example isValidDateTime("2024-02-30T12:34:56") // false (invalid date)
+ * @example isValidDateTime("2024-02-29T12:34:56[America/New_York]") // true (time zone annotation ignored)
+ * @example isValidDateTime("2024-02-29T12:34:56[!foo=bar]") // false (unknown critical annotation)
+ * @example isValidDateTime("2024-02-29T12:34:56[u-ca=hebrew]") // false (non-ISO calendar)
  * @example isValidDateTime("2024-02-29T24:00:00") // false (invalid time)
  * @example isValidDateTime("2024-02-29T23:59:60") // false (leap second)
  */
 export function isValidDateTime(value) {
-    if (isLeapSecond(value)) {
+    const body = isoStringBody(value);
+    if (isLeapSecond(body)) {
         return false;
     }
-    if (!plainDateTime.test(value)) {
+    if (!plainDateTime.test(body)) {
         return false;
     }
     try {
-        Temporal.PlainDateTime.from(value);
-        return true;
+        return Temporal.PlainDateTime.from(value).calendarId === "iso8601";
     }
     catch {
         return false;

package/dist/plain/validate/isValidDateTimeRange.d.ts

@@ -2,7 +2,8 @@
  * Return true if `value1` and `value2` form a valid datetime range — both parseable as
  * ISO PlainDateTime strings and `value1 <= value2`.
  *
- * - Both inputs must be ISO 8601 datetime strings (e.g. `"2024-01-01T10:00:00"`).
+ * - Both inputs must be ISO 8601 datetime strings (e.g. `"2024-01-01T10:00:00"`), as
+ *   `isValidDateTime` accepts, annotations included.
  * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  *
@@ -15,7 +16,7 @@
  * @example isValidDateTimeRange({ value1: "2024-12-31T23:59:59", value2: "2024-01-01T10:00:00" }) // false
  * @example isValidDateTimeRange({ value1: "2024-01-01T10:00:00", value2: "2024-01-01T10:00:00", options: { allowEqual: true } }) // true
  */
-export declare function isValidDateTimeRange({ value1, value2, options, }: {
+export declare function isValidDateTimeRange(props: {
     value1: string;
     value2: string;
     options?: {

package/dist/plain/validate/isValidDateTimeRange.js

@@ -1,10 +1,13 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { plainDateTime } from "../../regex/index.js";
+import { isValidDateTime } from "./isValidDateTime.js";
+import { isObject, isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true if `value1` and `value2` form a valid datetime range — both parseable as
  * ISO PlainDateTime strings and `value1 <= value2`.
  *
- * - Both inputs must be ISO 8601 datetime strings (e.g. `"2024-01-01T10:00:00"`).
+ * - Both inputs must be ISO 8601 datetime strings (e.g. `"2024-01-01T10:00:00"`), as
+ *   `isValidDateTime` accepts, annotations included.
  * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  *
@@ -17,23 +20,35 @@ import { plainDateTime } from "../../regex/index.js";
  * @example isValidDateTimeRange({ value1: "2024-12-31T23:59:59", value2: "2024-01-01T10:00:00" }) // false
  * @example isValidDateTimeRange({ value1: "2024-01-01T10:00:00", value2: "2024-01-01T10:00:00", options: { allowEqual: true } }) // true
  */
-export function isValidDateTimeRange({ value1, value2, options, }) {
-    if (typeof value1 !== "string" || typeof value2 !== "string") {
-        return false;
-    }
-    if (!plainDateTime.test(value1) || !plainDateTime.test(value2)) {
-        return false;
-    }
+export function isValidDateTimeRange(props) {
     try {
-        const dt1 = Temporal.PlainDateTime.from(value1);
-        const dt2 = Temporal.PlainDateTime.from(value2);
-        const cmp = Temporal.PlainDateTime.compare(dt1, dt2);
-        if (options?.allowEqual) {
-            return cmp <= 0;
+        if (!isObject(props))
+            return false;
+        const { value1, value2, options } = props;
+        if (!isOptionsArgument(options))
+            return false;
+        if (typeof value1 !== "string" || typeof value2 !== "string") {
+            return false;
+        }
+        if (!isValidDateTime(value1) || !isValidDateTime(value2)) {
+            return false;
+        }
+        try {
+            const dt1 = Temporal.PlainDateTime.from(value1);
+            const dt2 = Temporal.PlainDateTime.from(value2);
+            const cmp = Temporal.PlainDateTime.compare(dt1, dt2);
+            if (options?.allowEqual) {
+                return cmp <= 0;
+            }
+            return cmp < 0;
+        }
+        catch {
+            return false;
         }
-        return cmp < 0;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/plain/validate/isValidIsoDateLike.d.ts

@@ -2,7 +2,10 @@
  * Return true when the input is a valid PlainDate or PlainDateTime ISO string.
  *
  * - Accepts both PlainDate ("2024-02-29") and PlainDateTime ("2024-02-29T12:34:56") formats.
- * - Uses regex to check format before parsing.
+ * - The part before the first annotation must match `plainDate` or `plainDateTime`.
+ * - Reads RFC 9557 annotations as `Temporal.PlainDate.from` / `Temporal.PlainDateTime.from` do:
+ *   elective ones and a time zone annotation are ignored, an unknown critical one is rejected, and
+ *   the calendar must be ISO.
  * - Rejects leap seconds and invalid dates/times.
  *
  * @param value ISO PlainDate or PlainDateTime string
@@ -13,5 +16,7 @@
  * @example isValidIsoDateLike("2024-02-29T12:34:56") // true
  * @example isValidIsoDateLike("2024-02-29T24:00:00") // false (invalid time)
  * @example isValidIsoDateLike("2024-12-31T23:59:60") // false (leap second)
+ * @example isValidIsoDateLike("2024-02-29[u-ca=iso8601]") // true
+ * @example isValidIsoDateLike("2024-02-29[u-ca=hebrew]") // false (non-ISO calendar)
  */
 export declare function isValidIsoDateLike(value: string): boolean;

package/dist/plain/validate/isValidIsoDateLike.js

@@ -1,11 +1,15 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isoStringBody } from "../../internal/isoStringBody.js";
 import { plainDate, plainDateTime } from "../../regex/index.js";
 import { isLeapSecond } from "./isLeapSecond.js";
 /**
  * Return true when the input is a valid PlainDate or PlainDateTime ISO string.
  *
  * - Accepts both PlainDate ("2024-02-29") and PlainDateTime ("2024-02-29T12:34:56") formats.
- * - Uses regex to check format before parsing.
+ * - The part before the first annotation must match `plainDate` or `plainDateTime`.
+ * - Reads RFC 9557 annotations as `Temporal.PlainDate.from` / `Temporal.PlainDateTime.from` do:
+ *   elective ones and a time zone annotation are ignored, an unknown critical one is rejected, and
+ *   the calendar must be ISO.
  * - Rejects leap seconds and invalid dates/times.
  *
  * @param value ISO PlainDate or PlainDateTime string
@@ -16,24 +20,25 @@ import { isLeapSecond } from "./isLeapSecond.js";
  * @example isValidIsoDateLike("2024-02-29T12:34:56") // true
  * @example isValidIsoDateLike("2024-02-29T24:00:00") // false (invalid time)
  * @example isValidIsoDateLike("2024-12-31T23:59:60") // false (leap second)
+ * @example isValidIsoDateLike("2024-02-29[u-ca=iso8601]") // true
+ * @example isValidIsoDateLike("2024-02-29[u-ca=hebrew]") // false (non-ISO calendar)
  */
 export function isValidIsoDateLike(value) {
-    if (isLeapSecond(value)) {
+    const body = isoStringBody(value);
+    if (isLeapSecond(body)) {
         return false;
     }
-    if (plainDate.test(value)) {
+    if (plainDate.test(body)) {
         try {
-            Temporal.PlainDate.from(value);
-            return true;
+            return Temporal.PlainDate.from(value).calendarId === "iso8601";
         }
         catch {
             return false;
         }
     }
-    if (plainDateTime.test(value)) {
+    if (plainDateTime.test(body)) {
         try {
-            Temporal.PlainDateTime.from(value);
-            return true;
+            return Temporal.PlainDateTime.from(value).calendarId === "iso8601";
         }
         catch {
             return false;

package/dist/plain/validate/isValidTime.d.ts

@@ -1,7 +1,10 @@
 /**
  * Return true when `value` is a valid ISO PlainTime string.
  *
- * - Uses regex to check format before parsing.
+ * - The part before the first annotation must match `plainTime`.
+ * - Reads RFC 9557 annotations as `Temporal.PlainTime.from` does: elective ones (`[foo=bar]`), a
+ *   time zone annotation and a calendar annotation are ignored (a time has no calendar), and an
+ *   unknown critical one (`[!foo=bar]`) is rejected.
  * - Rejects leap seconds (e.g., "23:59:60").
  * - Rejects invalid times (e.g., "24:00:00", "23:60:00").
  *
@@ -10,6 +13,8 @@
  *
  * @example isValidTime("12:34:56") // true
  * @example isValidTime("24:00:00") // false (invalid hour)
+ * @example isValidTime("12:34:56[u-ca=hebrew]") // true (calendar annotation ignored)
+ * @example isValidTime("12:34:56[!foo=bar]") // false (unknown critical annotation)
  * @example isValidTime("23:60:00") // false (invalid minute)
  * @example isValidTime("23:59:60") // false (leap second)
  */