@northguild/gmt 1.14.2 → 1.16.0

package/dist/plain/parse/parseTimeWithPattern.js

@@ -48,38 +48,44 @@ import { parseValueWithPattern, TIME_PATTERN_FIELDS } from "../../internal/index
  *
  * @param value The string to decode (e.g. "02:30:45 PM")
  * @param pattern The token pattern describing `value`'s shape (e.g. "hh:mm:ss a")
- * @param locale Optional BCP 47 locale for the meridiem token (default "en-US")
+ * @param locale Optional BCP 47 locale tag, or a preference list of tags, for the meridiem token (default "en-US")
  * @returns ISO `PlainTime` string, or "" on no match, malformed pattern, or invalid input
  *
  * @example parseTimeWithPattern("14:30:45", "HH:mm:ss") // "14:30:45"
  * @example parseTimeWithPattern("02:30:45 PM", "hh:mm:ss a") // "14:30:45"
  * @example parseTimeWithPattern("25:00", "HH:mm") // "" (shape-valid, not a real time)
  * @example parseTimeWithPattern("2024-03-15", "yyyy-MM-dd") // "" (date token in a time-only pattern)
+ * @example parseTimeWithPattern("午後 10:20", "a h:mm", ["ja-JP", "en-US"]) // "22:20:00"
  */
 export function parseTimeWithPattern(value, pattern, locale) {
-    if (typeof value !== "string")
-        return "";
-    if (typeof pattern !== "string")
-        return "";
-    if (locale !== undefined && typeof locale !== "string")
-        return "";
-    const fields = parseValueWithPattern(value, pattern, locale, TIME_PATTERN_FIELDS);
-    if (fields === null)
-        return "";
     try {
-        // The regex only proved `value` has the right *shape* for `pattern`
-        // (e.g. "25:00" matches "HH:mm") — Temporal is what proves the time
-        // is real: `overflow: "reject"` throws instead of silently clamping
-        // an out-of-range field, which is what the default "constrain" would
-        // do.
-        return Temporal.PlainTime.from({
-            hour: fields.hour,
-            minute: fields.minute,
-            second: fields.second,
-            millisecond: fields.millisecond,
-        }, { overflow: "reject" }).toString();
+        if (typeof value !== "string")
+            return "";
+        if (typeof pattern !== "string")
+            return "";
+        const fields = parseValueWithPattern(value, pattern, locale, TIME_PATTERN_FIELDS);
+        if (fields === null)
+            return "";
+        try {
+            // The regex only proved `value` has the right *shape* for `pattern`
+            // (e.g. "25:00" matches "HH:mm") — Temporal is what proves the time
+            // is real: `overflow: "reject"` throws instead of silently clamping
+            // an out-of-range field, which is what the default "constrain" would
+            // do.
+            return Temporal.PlainTime.from({
+                hour: fields.hour,
+                minute: fields.minute,
+                second: fields.second,
+                millisecond: fields.millisecond,
+            }, { overflow: "reject" }).toString();
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/parse/parseUnitFromDate.d.ts

@@ -1,13 +1,18 @@
+import { Temporal } from "@js-temporal/polyfill";
 /**
  * Return a specific date unit extracted from a PlainDate string.
  *
  * - Extracts "year", "month", "day", "week", or "dayOfWeek" from a PlainDate.
  * - Returns zero-padded string for month and day.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
+ * - `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 "".
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainDate string
  * @param unit unit to extract from the date
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations; a non-object value (such as `null`) is invalid
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDate("2024-03-15", "year") // "2024"
@@ -15,9 +20,11 @@
  * @example parseUnitFromDate("2024-03-15", "day") // "15"
  * @example parseUnitFromDate("2024-03-15", "week") // "11"
  * @example parseUnitFromDate("2024-03-15", "dayOfWeek") // "5"
+ * @example parseUnitFromDate("2024-03-15", "months") // "03"
+ * @example parseUnitFromDate("2024-12-31", "week", { weekStartsOn: "sunday" }) // "1"
  * @example parseUnitFromDate("invalid", "year") // ""
  * @example parseUnitFromDate("2024-01-01", "week", { weekStartsOn: "sunday" }) // "1"
  */
-export declare function parseUnitFromDate(value: string, unit: "year" | "month" | "day" | "week" | "dayOfWeek", optionsArg?: {
+export declare function parseUnitFromDate(value: string, unit: Temporal.SmallestUnit<"year" | "month" | "day" | "week"> | "dayOfWeek", optionsArg?: {
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/plain/parse/parseUnitFromDate.js

@@ -1,16 +1,23 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../calculate/getWeekNumber.js";
 import { isValidDate } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a specific date unit extracted from a PlainDate string.
  *
  * - Extracts "year", "month", "day", "week", or "dayOfWeek" from a PlainDate.
  * - Returns zero-padded string for month and day.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
+ * - `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 "".
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainDate string
  * @param unit unit to extract from the date
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations; a non-object value (such as `null`) is invalid
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDate("2024-03-15", "year") // "2024"
@@ -18,32 +25,45 @@ import { isValidDate } from "../validate/index.js";
  * @example parseUnitFromDate("2024-03-15", "day") // "15"
  * @example parseUnitFromDate("2024-03-15", "week") // "11"
  * @example parseUnitFromDate("2024-03-15", "dayOfWeek") // "5"
+ * @example parseUnitFromDate("2024-03-15", "months") // "03"
+ * @example parseUnitFromDate("2024-12-31", "week", { weekStartsOn: "sunday" }) // "1"
  * @example parseUnitFromDate("invalid", "year") // ""
  * @example parseUnitFromDate("2024-01-01", "week", { weekStartsOn: "sunday" }) // "1"
  */
 export function parseUnitFromDate(value, unit, optionsArg) {
-    if (!isValidDate(value)) {
-        return "";
-    }
-    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
     try {
-        const date = Temporal.PlainDate.from(value);
-        switch (unit) {
-            case "year":
-                return date.year.toString();
-            case "month":
-                return date.month.toString().padStart(2, "0");
-            case "day":
-                return date.day.toString().padStart(2, "0");
-            case "week":
-                return (getWeekNumber(value, weekStartsOn) ?? 0).toString();
-            case "dayOfWeek":
-                return date.dayOfWeek.toString();
-            default:
-                return "";
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        if (!isValidDate(value) || weekStartsOn === null) {
+            return "";
+        }
+        try {
+            const date = Temporal.PlainDate.from(value);
+            switch (resolveDateTimeUnit(unit)) {
+                case "year":
+                    return date.year.toString();
+                case "month":
+                    return date.month.toString().padStart(2, "0");
+                case "day":
+                    return date.day.toString().padStart(2, "0");
+                case "week":
+                    return (getWeekNumber(value, weekStartsOn) ?? 0).toString();
+                case "dayOfWeek":
+                    return date.dayOfWeek.toString();
+                default:
+                    return "";
+            }
+        }
+        catch {
+            return "";
         }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/parse/parseUnitFromDateTime.d.ts

@@ -1,22 +1,30 @@
+import { Temporal } from "@js-temporal/polyfill";
 /**
  * Return a specific unit extracted from a PlainDateTime string.
  *
- * - Extracts "year", "month", "day", "week", "dayOfWeek", "hour", "minute", "second", or "millisecond" from a PlainDateTime.
+ * - Extracts "year", "month", "day", "week", "dayOfWeek", "hour", "minute", "second",
+ *   "millisecond", "microsecond" or "nanosecond" from a PlainDateTime (the last three are
+ *   Temporal's 0-999 fields, zero-padded to 3 digits).
  * - Returns zero-padded string for most units.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
+ * - `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 "".
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainDateTime string
  * @param unit unit to extract from the datetime
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations; a non-object value (such as `null`) is invalid
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "year") // "2024"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "week") // "11"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "hour") // "14"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "millisecond") // "123"
+ * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "hours") // "14"
  * @example parseUnitFromDateTime("invalid", "year") // ""
  * @example parseUnitFromDateTime("2024-01-01T00:00:00", "week", { weekStartsOn: "sunday" }) // "1"
  */
-export declare function parseUnitFromDateTime(value: string, unit: "year" | "month" | "day" | "week" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond", optionsArg?: {
+export declare function parseUnitFromDateTime(value: string, unit: Temporal.SmallestUnit<"year" | "month" | "day" | "week" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"> | "dayOfWeek", optionsArg?: {
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/plain/parse/parseUnitFromDateTime.js

@@ -1,56 +1,82 @@
+// 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 { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../calculate/getWeekNumber.js";
 import { isValidDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a specific unit extracted from a PlainDateTime string.
  *
- * - Extracts "year", "month", "day", "week", "dayOfWeek", "hour", "minute", "second", or "millisecond" from a PlainDateTime.
+ * - Extracts "year", "month", "day", "week", "dayOfWeek", "hour", "minute", "second",
+ *   "millisecond", "microsecond" or "nanosecond" from a PlainDateTime (the last three are
+ *   Temporal's 0-999 fields, zero-padded to 3 digits).
  * - Returns zero-padded string for most units.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
+ * - `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 "".
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainDateTime string
  * @param unit unit to extract from the datetime
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations; a non-object value (such as `null`) is invalid
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "year") // "2024"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "week") // "11"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "hour") // "14"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "millisecond") // "123"
+ * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "hours") // "14"
  * @example parseUnitFromDateTime("invalid", "year") // ""
  * @example parseUnitFromDateTime("2024-01-01T00:00:00", "week", { weekStartsOn: "sunday" }) // "1"
  */
 export function parseUnitFromDateTime(value, unit, optionsArg) {
-    if (!isValidDateTime(value)) {
-        return "";
-    }
-    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
     try {
-        const dateTime = Temporal.PlainDateTime.from(value);
-        switch (unit) {
-            case "year":
-                return dateTime.year.toString();
-            case "month":
-                return dateTime.month.toString().padStart(2, "0");
-            case "day":
-                return dateTime.day.toString().padStart(2, "0");
-            case "week":
-                return (getWeekNumber(value, weekStartsOn) ?? 0).toString();
-            case "dayOfWeek":
-                return dateTime.dayOfWeek.toString();
-            case "hour":
-                return dateTime.hour.toString().padStart(2, "0");
-            case "minute":
-                return dateTime.minute.toString().padStart(2, "0");
-            case "second":
-                return dateTime.second.toString().padStart(2, "0");
-            case "millisecond":
-                return dateTime.millisecond.toString().padStart(3, "0");
-            default:
-                return "";
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        if (!isValidDateTime(value) || weekStartsOn === null) {
+            return "";
+        }
+        try {
+            const dateTime = Temporal.PlainDateTime.from(value);
+            switch (resolveDateTimeUnit(unit)) {
+                case "year":
+                    return dateTime.year.toString();
+                case "month":
+                    return dateTime.month.toString().padStart(2, "0");
+                case "day":
+                    return dateTime.day.toString().padStart(2, "0");
+                case "week":
+                    return (getWeekNumber(dateTime.toPlainDate().toString(), weekStartsOn) ?? 0).toString();
+                case "dayOfWeek":
+                    return dateTime.dayOfWeek.toString();
+                case "hour":
+                    return dateTime.hour.toString().padStart(2, "0");
+                case "minute":
+                    return dateTime.minute.toString().padStart(2, "0");
+                case "second":
+                    return dateTime.second.toString().padStart(2, "0");
+                case "millisecond":
+                    return dateTime.millisecond.toString().padStart(3, "0");
+                case "microsecond":
+                    return dateTime.microsecond.toString().padStart(3, "0");
+                case "nanosecond":
+                    return dateTime.nanosecond.toString().padStart(3, "0");
+                default:
+                    return "";
+            }
+        }
+        catch {
+            return "";
         }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/parse/parseUnitFromTime.d.ts

@@ -1,8 +1,12 @@
+import { Temporal } from "@js-temporal/polyfill";
 /**
  * Return a specific time unit extracted from a PlainTime string.
  *
- * - Extracts "hour", "minute", "second", or "millisecond" from a PlainTime.
- * - Returns zero-padded string for hour, minute, second (2 digits) and millisecond (3 digits).
+ * - Extracts "hour", "minute", "second", "millisecond", "microsecond" or "nanosecond" from a
+ *   PlainTime.
+ * - Returns zero-padded string for hour, minute, second (2 digits) and millisecond, microsecond and
+ *   nanosecond (3 digits, each the 0-999 Temporal field).
+ * - `unit` accepts the singular or plural name (`"hour"` or `"hours"`), as Temporal does.
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainTime string
@@ -13,6 +17,8 @@
  * @example parseUnitFromTime("14:30:45.123", "minute") // "30"
  * @example parseUnitFromTime("14:30:45.123", "second") // "45"
  * @example parseUnitFromTime("14:30:45.123", "millisecond") // "123"
+ * @example parseUnitFromTime("14:30:45.123", "milliseconds") // "123"
+ * @example parseUnitFromTime("14:30:45.123456789", "nanosecond") // "789"
  * @example parseUnitFromTime("invalid", "hour") // ""
  */
-export declare function parseUnitFromTime(value: string, unit: "hour" | "minute" | "second" | "millisecond"): string;
+export declare function parseUnitFromTime(value: string, unit: Temporal.SmallestUnit<"hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">): string;

package/dist/plain/parse/parseUnitFromTime.js

@@ -1,10 +1,14 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 import { isValidTime } from "../validate/index.js";
 /**
  * Return a specific time unit extracted from a PlainTime string.
  *
- * - Extracts "hour", "minute", "second", or "millisecond" from a PlainTime.
- * - Returns zero-padded string for hour, minute, second (2 digits) and millisecond (3 digits).
+ * - Extracts "hour", "minute", "second", "millisecond", "microsecond" or "nanosecond" from a
+ *   PlainTime.
+ * - Returns zero-padded string for hour, minute, second (2 digits) and millisecond, microsecond and
+ *   nanosecond (3 digits, each the 0-999 Temporal field).
+ * - `unit` accepts the singular or plural name (`"hour"` or `"hours"`), as Temporal does.
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainTime string
@@ -15,6 +19,8 @@ import { isValidTime } from "../validate/index.js";
  * @example parseUnitFromTime("14:30:45.123", "minute") // "30"
  * @example parseUnitFromTime("14:30:45.123", "second") // "45"
  * @example parseUnitFromTime("14:30:45.123", "millisecond") // "123"
+ * @example parseUnitFromTime("14:30:45.123", "milliseconds") // "123"
+ * @example parseUnitFromTime("14:30:45.123456789", "nanosecond") // "789"
  * @example parseUnitFromTime("invalid", "hour") // ""
  */
 export function parseUnitFromTime(value, unit) {
@@ -23,7 +29,7 @@ export function parseUnitFromTime(value, unit) {
     }
     try {
         const time = Temporal.PlainTime.from(value);
-        switch (unit) {
+        switch (resolveDateTimeUnit(unit)) {
             case "hour":
                 return time.hour.toString().padStart(2, "0");
             case "minute":
@@ -32,6 +38,10 @@ export function parseUnitFromTime(value, unit) {
                 return time.second.toString().padStart(2, "0");
             case "millisecond":
                 return time.millisecond.toString().padStart(3, "0");
+            case "microsecond":
+                return time.microsecond.toString().padStart(3, "0");
+            case "nanosecond":
+                return time.nanosecond.toString().padStart(3, "0");
             default:
                 return "";
         }

package/dist/plain/parse/parseWeekFromDate.d.ts

@@ -2,6 +2,10 @@
  * Return the week number for a given ISO 8601 date string.
  *
  * - By default uses ISO weeks (Monday-based).
+ * - `weekStartsOn: "sunday"` is the UTS #35 week of the week-year with a Sunday first day and
+ *   minimal days 1 (week 1 holds 1 January, so late-December days can be week 1), while `"monday"`
+ *   is the ISO 8601 week of the week-year; both are 1–53 — see `getWeekNumber`.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO date string
@@ -13,6 +17,7 @@
  * @example parseWeekFromDate("2024-12-31") // 1
  * @example parseWeekFromDate("2024-01-01", { weekStartsOn: "sunday" }) // 1
  * @example parseWeekFromDate("invalid") // null
+ * @example parseWeekFromDate("2024-12-31", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
  */
 export declare function parseWeekFromDate(value: string, optionsArg?: {
     weekStartsOn?: "monday" | "sunday";

package/dist/plain/parse/parseWeekFromDate.js

@@ -1,9 +1,15 @@
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../calculate/getWeekNumber.js";
 import { isValidDate } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number for a given ISO 8601 date string.
  *
  * - By default uses ISO weeks (Monday-based).
+ * - `weekStartsOn: "sunday"` is the UTS #35 week of the week-year with a Sunday first day and
+ *   minimal days 1 (week 1 holds 1 January, so late-December days can be week 1), while `"monday"`
+ *   is the ISO 8601 week of the week-year; both are 1–53 — see `getWeekNumber`.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO date string
@@ -15,16 +21,29 @@ import { isValidDate } from "../validate/index.js";
  * @example parseWeekFromDate("2024-12-31") // 1
  * @example parseWeekFromDate("2024-01-01", { weekStartsOn: "sunday" }) // 1
  * @example parseWeekFromDate("invalid") // null
+ * @example parseWeekFromDate("2024-12-31", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
  */
 export function parseWeekFromDate(value, optionsArg) {
-    if (!isValidDate(value)) {
-        return null;
-    }
-    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
     try {
-        return getWeekNumber(value, weekStartsOn);
+        if (!isOptionsArgument(optionsArg)) {
+            return null;
+        }
+        if (!isValidDate(value)) {
+            return null;
+        }
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        if (weekStartsOn === null)
+            return null;
+        try {
+            return getWeekNumber(value, weekStartsOn);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/plain/parse/parseWeekFromDateTime.d.ts

@@ -2,6 +2,10 @@
  * Return the week number for a given ISO 8601 datetime string.
  *
  * - By default uses ISO weeks (Monday-based).
+ * - `weekStartsOn: "sunday"` is the UTS #35 week of the week-year with a Sunday first day and
+ *   minimal days 1 (week 1 holds 1 January, so late-December days can be week 1), while `"monday"`
+ *   is the ISO 8601 week of the week-year; both are 1–53 — see `getWeekNumber`.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO 8601 datetime string
@@ -12,6 +16,7 @@
  * @example parseWeekFromDateTime("2024-01-08T00:00:00") // 2
  * @example parseWeekFromDateTime("2024-01-01T00:00:00", { weekStartsOn: "sunday" }) // 1
  * @example parseWeekFromDateTime("invalid") // null
+ * @example parseWeekFromDateTime("2024-12-31T12:00:00", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
  */
 export declare function parseWeekFromDateTime(value: string, optionsArg?: {
     weekStartsOn?: "monday" | "sunday";

package/dist/plain/parse/parseWeekFromDateTime.js

@@ -1,9 +1,16 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../calculate/getWeekNumber.js";
 import { isValidDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number for a given ISO 8601 datetime string.
  *
  * - By default uses ISO weeks (Monday-based).
+ * - `weekStartsOn: "sunday"` is the UTS #35 week of the week-year with a Sunday first day and
+ *   minimal days 1 (week 1 holds 1 January, so late-December days can be week 1), while `"monday"`
+ *   is the ISO 8601 week of the week-year; both are 1–53 — see `getWeekNumber`.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO 8601 datetime string
@@ -14,16 +21,30 @@ import { isValidDateTime } from "../validate/index.js";
  * @example parseWeekFromDateTime("2024-01-08T00:00:00") // 2
  * @example parseWeekFromDateTime("2024-01-01T00:00:00", { weekStartsOn: "sunday" }) // 1
  * @example parseWeekFromDateTime("invalid") // null
+ * @example parseWeekFromDateTime("2024-12-31T12:00:00", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
  */
 export function parseWeekFromDateTime(value, optionsArg) {
-    if (!isValidDateTime(value)) {
-        return null;
-    }
-    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
     try {
-        return getWeekNumber(value, weekStartsOn);
+        if (!isOptionsArgument(optionsArg)) {
+            return null;
+        }
+        if (!isValidDateTime(value)) {
+            return null;
+        }
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        if (weekStartsOn === null)
+            return null;
+        try {
+            // getWeekNumber takes a PlainDate string only, so pass the date half.
+            return getWeekNumber(Temporal.PlainDateTime.from(value).toPlainDate().toString(), weekStartsOn);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -1,16 +1,34 @@
 /**
- * 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 declare function isLeapSecond(value: string): boolean;