@northguild/gmt 1.15.0 → 1.16.0

package/dist/plain/map/mapDatesInRange.js

@@ -1,46 +1,82 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDate } from "../validate/index.js";
+import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js";
 /**
  * Return an array of ISO PlainDate strings between `startDate` and `endDate` inclusive.
  *
  * - Generates dates with optional step (default 1 day).
  * - Returns [] if start > end, invalid inputs, or step <= 0.
+ * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when the
+ *   range holds more dates than that, it returns `[]` without generating any. An invalid
+ *   `maxPieces` also returns `[]`.
+ * - An explicit `undefined` `stepDays` is the default step, so `(start, end, undefined, options)`
+ *   reaches `options`. **Compatibility:** before 1.16.0 it returned `[]`.
+ * - **End-inclusive, where the `interval*` functions are half-open.** This enumerates the dates a
+ *   range covers, so `endDate` is one of them; an interval bounds a span as `[start, end)`, so its
+ *   `end` is not. The same pair therefore yields one more date here than `intervalCountDate`
+ *   counts. To read one set of bounds both ways, pass `addDate(endDate, { days: 1 })` to the
+ *   `interval*` call, or `subtractDate(endDate, { days: 1 })` to this one.
  *
  * @param startDate ISO PlainDate string for the first date
  * @param endDate ISO PlainDate string for the last date (inclusive)
  * @param stepDays optional number of days to step between results
+ * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
  * @returns array of ISO PlainDate strings, or [] on invalid input
  *
  * @example mapDatesInRange("2024-03-01", "2024-03-05") // ["2024-03-01", "2024-03-02", "2024-03-03", "2024-03-04", "2024-03-05"]
  * @example mapDatesInRange("2024-03-01", "2024-03-05", 2) // ["2024-03-01", "2024-03-03", "2024-03-05"]
+ * @example mapDatesInRange("+275760-09-11", "+275760-09-13") // ["+275760-09-11", "+275760-09-12", "+275760-09-13"] (a range ending on the last representable date)
  * @example mapDatesInRange("2024-03-05", "2024-03-01") // []
  * @example mapDatesInRange("invalid", "2024-03-05") // []
  * @example mapDatesInRange("2024-03-01", "invalid") // []
+ * @example mapDatesInRange("2024-03-01", "2024-03-03", undefined) // ["2024-03-01", "2024-03-02", "2024-03-03"] (undefined is the default step)
  * @example mapDatesInRange("2024-03-01", "2024-03-05", 0) // []
+ * @example mapDatesInRange("2024-03-01", "2024-03-05", 1, { maxPieces: 3 }) // [] (more dates than the limit)
+ * @example mapDatesInRange("2024-03-01", "2024-03-05", 1, { maxPieces: 10 }) // ["2024-03-01", "2024-03-02", "2024-03-03", "2024-03-04", "2024-03-05"]
  */
-export function mapDatesInRange(startDate, endDate, ...stepDaysInput) {
-    const resolvedStepDays = stepDaysInput.length === 0 ? 1 : stepDaysInput[0];
-    if (typeof resolvedStepDays !== "number" ||
-        !Number.isInteger(resolvedStepDays) ||
-        resolvedStepDays <= 0) {
-        return [];
-    }
-    if (!isValidDate(startDate) || !isValidDate(endDate)) {
-        return [];
-    }
+export function mapDatesInRange(startDate, endDate, stepDays, options) {
     try {
-        const start = Temporal.PlainDate.from(startDate);
-        const end = Temporal.PlainDate.from(endDate);
-        if (Temporal.PlainDate.compare(start, end) === 1) {
+        // An explicit undefined is the omitted argument, as TC39 GetOption treats it.
+        const resolvedStepDays = stepDays === undefined ? 1 : stepDays;
+        if (typeof resolvedStepDays !== "number" ||
+            !Number.isInteger(resolvedStepDays) ||
+            resolvedStepDays <= 0) {
+            return [];
+        }
+        const maxPieces = resolveMaxPieces(options);
+        if (maxPieces === null) {
+            return [];
+        }
+        if (!isValidDate(startDate) || !isValidDate(endDate)) {
             return [];
         }
-        const result = [];
-        for (let current = start; Temporal.PlainDate.compare(current, end) <= 0; current = current.add({ days: resolvedStepDays })) {
-            result.push(current.toString());
+        try {
+            const start = Temporal.PlainDate.from(startDate);
+            const end = Temporal.PlainDate.from(endDate);
+            if (Temporal.PlainDate.compare(start, end) === 1) {
+                return [];
+            }
+            const count = Math.floor(start.until(end).days / resolvedStepDays) + 1;
+            if (exceedsPieceLimit(count, maxPieces)) {
+                return [];
+            }
+            // Each date is anchored at the start (start + k·step) and only the `count` in-range dates are
+            // built, so no step past the end is taken — a range ending on Temporal's date limit keeps its
+            // dates instead of throwing on the step after the last one.
+            const result = [];
+            for (let index = 0; index < count; index++) {
+                result.push(start.add({ days: index * resolvedStepDays }).toString());
+            }
+            return result;
+        }
+        catch {
+            return [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

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

@@ -74,12 +74,13 @@
  *
  * @param value The string to decode (e.g. "03/15/2024 14:30:00")
  * @param pattern The token pattern describing `value`'s shape (e.g. "MM/dd/yyyy HH:mm:ss")
- * @param locale Optional BCP 47 locale for name-based tokens (default "en-US")
+ * @param locale Optional BCP 47 locale tag, or a preference list of tags, for name-based tokens (default "en-US")
  * @returns ISO `PlainDateTime` string, or "" on no match, malformed pattern, or invalid input
  *
  * @example parseDateTimeWithPattern("03/15/2024 14:30:00", "MM/dd/yyyy HH:mm:ss") // "2024-03-15T14:30:00"
  * @example parseDateTimeWithPattern("15-Mar-2024 02:30 PM", "dd-MMM-yyyy hh:mm a") // "2024-03-15T14:30:00"
  * @example parseDateTimeWithPattern("02/31/2024 14:30:00", "MM/dd/yyyy HH:mm:ss") // "" (shape-valid, not a real date)
  * @example parseDateTimeWithPattern("not a date", "MM/dd/yyyy HH:mm:ss") // ""
+ * @example parseDateTimeWithPattern("19 mai 2024 10:20", "d MMMM yyyy HH:mm", ["fr-FR", "en-US"]) // "2024-05-19T10:20:00"
  */
-export declare function parseDateTimeWithPattern(value: string, pattern: string, locale?: string): string;
+export declare function parseDateTimeWithPattern(value: string, pattern: string, locale?: string | string[]): string;

package/dist/plain/parse/parseDateTimeWithPattern.js

@@ -76,41 +76,47 @@ import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal
  *
  * @param value The string to decode (e.g. "03/15/2024 14:30:00")
  * @param pattern The token pattern describing `value`'s shape (e.g. "MM/dd/yyyy HH:mm:ss")
- * @param locale Optional BCP 47 locale for name-based tokens (default "en-US")
+ * @param locale Optional BCP 47 locale tag, or a preference list of tags, for name-based tokens (default "en-US")
  * @returns ISO `PlainDateTime` string, or "" on no match, malformed pattern, or invalid input
  *
  * @example parseDateTimeWithPattern("03/15/2024 14:30:00", "MM/dd/yyyy HH:mm:ss") // "2024-03-15T14:30:00"
  * @example parseDateTimeWithPattern("15-Mar-2024 02:30 PM", "dd-MMM-yyyy hh:mm a") // "2024-03-15T14:30:00"
  * @example parseDateTimeWithPattern("02/31/2024 14:30:00", "MM/dd/yyyy HH:mm:ss") // "" (shape-valid, not a real date)
  * @example parseDateTimeWithPattern("not a date", "MM/dd/yyyy HH:mm:ss") // ""
+ * @example parseDateTimeWithPattern("19 mai 2024 10:20", "d MMMM yyyy HH:mm", ["fr-FR", "en-US"]) // "2024-05-19T10:20:00"
  */
 export function parseDateTimeWithPattern(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, DATE_TIME_PATTERN_FIELDS);
-    if (fields === null)
-        return "";
     try {
-        // The regex only proved `value` has the right *shape* for `pattern`
-        // (e.g. "02/31/2024 14:30:00" matches "MM/dd/yyyy HH:mm:ss") —
-        // Temporal is what proves the value is real: `overflow: "reject"`
-        // throws instead of silently clamping an out-of-range field, which
-        // is what the default "constrain" would do.
-        return Temporal.PlainDateTime.from({
-            year: fields.year,
-            month: fields.month,
-            day: fields.day,
-            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, DATE_TIME_PATTERN_FIELDS);
+        if (fields === null)
+            return "";
+        try {
+            // The regex only proved `value` has the right *shape* for `pattern`
+            // (e.g. "02/31/2024 14:30:00" matches "MM/dd/yyyy HH:mm:ss") —
+            // Temporal is what proves the value is real: `overflow: "reject"`
+            // throws instead of silently clamping an out-of-range field, which
+            // is what the default "constrain" would do.
+            return Temporal.PlainDateTime.from({
+                year: fields.year,
+                month: fields.month,
+                day: fields.day,
+                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/parseDateWithPattern.d.ts

@@ -57,12 +57,13 @@
  *
  * @param value The string to decode (e.g. "03/15/2024")
  * @param pattern The token pattern describing `value`'s shape (e.g. "MM/dd/yyyy")
- * @param locale Optional BCP 47 locale for name-based tokens (default "en-US")
+ * @param locale Optional BCP 47 locale tag, or a preference list of tags, for name-based tokens (default "en-US")
  * @returns ISO `PlainDate` string, or "" on no match, malformed pattern, or invalid input
  *
  * @example parseDateWithPattern("03/15/2024", "MM/dd/yyyy") // "2024-03-15"
  * @example parseDateWithPattern("15-Mar-2024", "dd-MMM-yyyy") // "2024-03-15"
  * @example parseDateWithPattern("02/31/2024", "MM/dd/yyyy") // "" (shape-valid, not a real date)
  * @example parseDateWithPattern("14:30", "HH:mm") // "" (time token in a date-only pattern)
+ * @example parseDateWithPattern("19 mai 2024", "d MMMM yyyy", ["fr-FR", "en-US"]) // "2024-05-19"
  */
-export declare function parseDateWithPattern(value: string, pattern: string, locale?: string): string;
+export declare function parseDateWithPattern(value: string, pattern: string, locale?: string | string[]): string;

package/dist/plain/parse/parseDateWithPattern.js

@@ -59,33 +59,39 @@ import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index
  *
  * @param value The string to decode (e.g. "03/15/2024")
  * @param pattern The token pattern describing `value`'s shape (e.g. "MM/dd/yyyy")
- * @param locale Optional BCP 47 locale for name-based tokens (default "en-US")
+ * @param locale Optional BCP 47 locale tag, or a preference list of tags, for name-based tokens (default "en-US")
  * @returns ISO `PlainDate` string, or "" on no match, malformed pattern, or invalid input
  *
  * @example parseDateWithPattern("03/15/2024", "MM/dd/yyyy") // "2024-03-15"
  * @example parseDateWithPattern("15-Mar-2024", "dd-MMM-yyyy") // "2024-03-15"
  * @example parseDateWithPattern("02/31/2024", "MM/dd/yyyy") // "" (shape-valid, not a real date)
  * @example parseDateWithPattern("14:30", "HH:mm") // "" (time token in a date-only pattern)
+ * @example parseDateWithPattern("19 mai 2024", "d MMMM yyyy", ["fr-FR", "en-US"]) // "2024-05-19"
  */
 export function parseDateWithPattern(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, DATE_PATTERN_FIELDS);
-    if (fields === null)
-        return "";
     try {
-        // The regex only proved `value` has the right *shape* for `pattern`
-        // (e.g. "02/31/2024" matches "MM/dd/yyyy") — Temporal is what proves
-        // the date is real: `overflow: "reject"` throws instead of silently
-        // clamping Feb 31 to Feb 29, which is what the default "constrain"
-        // would do.
-        return Temporal.PlainDate.from({ year: fields.year, month: fields.month, day: fields.day }, { overflow: "reject" }).toString();
+        if (typeof value !== "string")
+            return "";
+        if (typeof pattern !== "string")
+            return "";
+        const fields = parseValueWithPattern(value, pattern, locale, DATE_PATTERN_FIELDS);
+        if (fields === null)
+            return "";
+        try {
+            // The regex only proved `value` has the right *shape* for `pattern`
+            // (e.g. "02/31/2024" matches "MM/dd/yyyy") — Temporal is what proves
+            // the date is real: `overflow: "reject"` throws instead of silently
+            // clamping Feb 31 to Feb 29, which is what the default "constrain"
+            // would do.
+            return Temporal.PlainDate.from({ year: fields.year, month: fields.month, day: fields.day }, { 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/parseMicrosecondFromDateTime.d.ts

@@ -7,7 +7,8 @@
  * @param value ISO datetime string
  * @returns Microsecond (000-999) or "" on invalid input
  *
- * @example parseMicrosecondFromDateTime("2024-03-15T14:30:45.123") // "123"
+ * @example parseMicrosecondFromDateTime("2024-03-15T14:30:45.123") // "000"
+ * @example parseMicrosecondFromDateTime("2024-03-15T14:30:45.123456") // "456"
  * @example parseMicrosecondFromDateTime("2024-03-15T14:30:45.000") // "000"
  * @example parseMicrosecondFromDateTime("invalid") // ""
  */

package/dist/plain/parse/parseMicrosecondFromDateTime.js

@@ -9,7 +9,8 @@ import { isValidDateTime } from "../validate/index.js";
  * @param value ISO datetime string
  * @returns Microsecond (000-999) or "" on invalid input
  *
- * @example parseMicrosecondFromDateTime("2024-03-15T14:30:45.123") // "123"
+ * @example parseMicrosecondFromDateTime("2024-03-15T14:30:45.123") // "000"
+ * @example parseMicrosecondFromDateTime("2024-03-15T14:30:45.123456") // "456"
  * @example parseMicrosecondFromDateTime("2024-03-15T14:30:45.000") // "000"
  * @example parseMicrosecondFromDateTime("invalid") // ""
  */

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

@@ -4,7 +4,8 @@
  * @param value ISO time string
  * @returns Microsecond (000-999) or "" on invalid input
  *
- * @example parseMicrosecondFromTime("12:30:45.123") // "123"
+ * @example parseMicrosecondFromTime("12:30:45.123") // "000"
+ * @example parseMicrosecondFromTime("12:30:45.123456") // "456"
  * @example parseMicrosecondFromTime("12:30:45.000") // "000"
  * @example parseMicrosecondFromTime("invalid") // ""
  */

package/dist/plain/parse/parseMicrosecondFromTime.js

@@ -6,7 +6,8 @@ import { isValidTime } from "../validate/index.js";
  * @param value ISO time string
  * @returns Microsecond (000-999) or "" on invalid input
  *
- * @example parseMicrosecondFromTime("12:30:45.123") // "123"
+ * @example parseMicrosecondFromTime("12:30:45.123") // "000"
+ * @example parseMicrosecondFromTime("12:30:45.123456") // "456"
  * @example parseMicrosecondFromTime("12:30:45.000") // "000"
  * @example parseMicrosecondFromTime("invalid") // ""
  */

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

@@ -7,7 +7,8 @@
  * @param value ISO datetime string
  * @returns Nanosecond (000-999) or "" on invalid input
  *
- * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.123") // "123"
+ * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.123") // "000"
+ * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.123456789") // "789"
  * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.000") // "000"
  * @example parseNanosecondFromDateTime("invalid") // ""
  */

package/dist/plain/parse/parseNanosecondFromDateTime.js

@@ -9,7 +9,8 @@ import { isValidDateTime } from "../validate/index.js";
  * @param value ISO datetime string
  * @returns Nanosecond (000-999) or "" on invalid input
  *
- * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.123") // "123"
+ * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.123") // "000"
+ * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.123456789") // "789"
  * @example parseNanosecondFromDateTime("2024-03-15T14:30:45.000") // "000"
  * @example parseNanosecondFromDateTime("invalid") // ""
  */

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

@@ -7,7 +7,8 @@
  * @param value ISO time string
  * @returns Nanosecond (000-999) or "" on invalid input
  *
- * @example parseNanosecondFromTime("12:30:45.123") // "123"
+ * @example parseNanosecondFromTime("12:30:45.123") // "000"
+ * @example parseNanosecondFromTime("12:30:45.123456789") // "789"
  * @example parseNanosecondFromTime("12:30:45.000") // "000"
  * @example parseNanosecondFromTime("invalid") // ""
  */

package/dist/plain/parse/parseNanosecondFromTime.js

@@ -9,7 +9,8 @@ import { isValidTime } from "../validate/index.js";
  * @param value ISO time string
  * @returns Nanosecond (000-999) or "" on invalid input
  *
- * @example parseNanosecondFromTime("12:30:45.123") // "123"
+ * @example parseNanosecondFromTime("12:30:45.123") // "000"
+ * @example parseNanosecondFromTime("12:30:45.123456789") // "789"
  * @example parseNanosecondFromTime("12:30:45.000") // "000"
  * @example parseNanosecondFromTime("invalid") // ""
  */

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

@@ -1,22 +1,25 @@
 /**
- * Parse an ANSI SQL / ODBC datetime literal — the `YYYY-MM-DD HH:MM:SS` form
- * MySQL, SQLite, and standard SQL `DATETIME`/`TIMESTAMP` columns (without a
- * time zone) use — into a plain ISO 8601 datetime string.
+ * Parse a SQL timestamp literal without a time zone — the `YYYY-MM-DD HH:MM:SS[.fff]` form of
+ * standard SQL `TIMESTAMP` and MySQL/SQLite `DATETIME` columns — into a plain ISO 8601 datetime
+ * string.
  *
- * - **Plain only.** SQL's offset-carrying `TIMESTAMPTZ` literal is out of
- *   scope; see `formatSql`'s JSDoc.
- * - Requires the space separator and 2-digit zero-padded month/day/hour;
- *   unlike `parseRfc2822`'s lenient 1-2 digit day, a single-digit field is
- *   rejected — SQL's literal grammar has no variable-width form to accept.
- * - Fractional seconds, when present, are preserved as-is; the regex only
- *   proves shape — `Temporal.PlainDateTime.from` proves the value is a real
- *   calendar date/time.
+ * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, as `sqlDateTime`
+ *   matches: a space separator, a four-digit year `0001`–`9999` (no sign, no expanded year),
+ *   two-digit month, day, hour, minute and second (seconds are required), and an optional `.`
+ *   followed by up to 9 fraction digits.
+ * - **Plain only.** SQL's offset-carrying `TIMESTAMP WITH TIME ZONE` literal is out of scope; see
+ *   `formatSql`'s JSDoc.
+ * - The fraction is written as `Temporal.PlainDateTime#toString` writes it: trailing zeros are
+ *   dropped (`.500` → `.5`, `.000` → none), and a `.` with no digits is dropped. `Temporal.PlainDateTime.from`
+ *   proves the value is a real calendar date and time.
  *
- * @param value SQL datetime literal (e.g. "2024-03-15 14:30:00")
+ * @param value SQL timestamp literal (e.g. "2024-03-15 14:30:00")
  * @returns plain ISO 8601 datetime string, or "" on invalid input
  *
  * @example parseSql("2024-03-15 14:30:00") // "2024-03-15T14:30:00"
  * @example parseSql("2024-03-15 14:30:00.5") // "2024-03-15T14:30:00.5"
+ * @example parseSql("2024-03-15 14:30") // "" (seconds are required)
+ * @example parseSql("0000-01-01 00:00:00") // "" (year outside 0001–9999)
  * @example parseSql("2024-03-15T14:30:00") // "" (wrong separator)
  * @example parseSql("not a date") // ""
  */

package/dist/plain/parse/parseSql.js

@@ -1,24 +1,27 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { sqlDateTime } from "../../regex/index.js";
 /**
- * Parse an ANSI SQL / ODBC datetime literal — the `YYYY-MM-DD HH:MM:SS` form
- * MySQL, SQLite, and standard SQL `DATETIME`/`TIMESTAMP` columns (without a
- * time zone) use — into a plain ISO 8601 datetime string.
+ * Parse a SQL timestamp literal without a time zone — the `YYYY-MM-DD HH:MM:SS[.fff]` form of
+ * standard SQL `TIMESTAMP` and MySQL/SQLite `DATETIME` columns — into a plain ISO 8601 datetime
+ * string.
  *
- * - **Plain only.** SQL's offset-carrying `TIMESTAMPTZ` literal is out of
- *   scope; see `formatSql`'s JSDoc.
- * - Requires the space separator and 2-digit zero-padded month/day/hour;
- *   unlike `parseRfc2822`'s lenient 1-2 digit day, a single-digit field is
- *   rejected — SQL's literal grammar has no variable-width form to accept.
- * - Fractional seconds, when present, are preserved as-is; the regex only
- *   proves shape — `Temporal.PlainDateTime.from` proves the value is a real
- *   calendar date/time.
+ * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, as `sqlDateTime`
+ *   matches: a space separator, a four-digit year `0001`–`9999` (no sign, no expanded year),
+ *   two-digit month, day, hour, minute and second (seconds are required), and an optional `.`
+ *   followed by up to 9 fraction digits.
+ * - **Plain only.** SQL's offset-carrying `TIMESTAMP WITH TIME ZONE` literal is out of scope; see
+ *   `formatSql`'s JSDoc.
+ * - The fraction is written as `Temporal.PlainDateTime#toString` writes it: trailing zeros are
+ *   dropped (`.500` → `.5`, `.000` → none), and a `.` with no digits is dropped. `Temporal.PlainDateTime.from`
+ *   proves the value is a real calendar date and time.
  *
- * @param value SQL datetime literal (e.g. "2024-03-15 14:30:00")
+ * @param value SQL timestamp literal (e.g. "2024-03-15 14:30:00")
  * @returns plain ISO 8601 datetime string, or "" on invalid input
  *
  * @example parseSql("2024-03-15 14:30:00") // "2024-03-15T14:30:00"
  * @example parseSql("2024-03-15 14:30:00.5") // "2024-03-15T14:30:00.5"
+ * @example parseSql("2024-03-15 14:30") // "" (seconds are required)
+ * @example parseSql("0000-01-01 00:00:00") // "" (year outside 0001–9999)
  * @example parseSql("2024-03-15T14:30:00") // "" (wrong separator)
  * @example parseSql("not a date") // ""
  */
@@ -28,7 +31,7 @@ export function parseSql(value) {
     if (!sqlDateTime.test(value))
         return "";
     try {
-        return Temporal.PlainDateTime.from(value.replace(" ", "T")).toString();
+        return Temporal.PlainDateTime.from(value.replace(" ", "T").replace(/\.$/, "")).toString();
     }
     catch {
         return "";

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

@@ -46,12 +46,13 @@
  *
  * @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 declare function parseTimeWithPattern(value: string, pattern: string, locale?: string): string;
+export declare function parseTimeWithPattern(value: string, pattern: string, locale?: string | string[]): string;

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;