@northguild/gmt 1.14.2

package/dist/plain/locale/getLocaleMonthNames.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The calendar-name styles supported by GMT's locale name lookups.
+ *
+ * These mirror the `month`/`weekday` options of `Intl.DateTimeFormat`
+ * rather than inventing a GMT-specific vocabulary.
+ */
+export type LocaleNameStyle = "long" | "short" | "narrow";
+/**
+ * Return the 12 Gregorian calendar-month names for a locale, in calendar
+ * order (January first, December last — not alphabetical).
+ *
+ * - Uses the host runtime's `Intl` data via `Temporal.PlainDate`, so output
+ *   depends on the runtime's ICU build (full-ICU runtimes localize every
+ *   locale; partial-ICU runtimes fall back to English).
+ * - Restricted to the Gregorian calendar; non-Gregorian calendar variants
+ *   are out of scope for this function.
+ * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ *
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param style Optional name style: `"long"` (default), `"short"`, or `"narrow"`
+ * @returns 12-element array of month names in calendar order, or `[]` on invalid input
+ *
+ * @example getLocaleMonthNames("en-US") // ["January", "February", ... "December"]
+ * @example getLocaleMonthNames("de-DE", "short") // ["Jan", "Feb", "Mär", ... "Dez"]
+ * @example getLocaleMonthNames("fr-FR", "narrow") // ["J", "F", "M", ... "D"]
+ * @example getLocaleMonthNames("not-a-locale") // []
+ */
+export declare function getLocaleMonthNames(locale: string, style?: LocaleNameStyle): string[];

package/dist/plain/locale/getLocaleMonthNames.js

@@ -0,0 +1,45 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return the 12 Gregorian calendar-month names for a locale, in calendar
+ * order (January first, December last — not alphabetical).
+ *
+ * - Uses the host runtime's `Intl` data via `Temporal.PlainDate`, so output
+ *   depends on the runtime's ICU build (full-ICU runtimes localize every
+ *   locale; partial-ICU runtimes fall back to English).
+ * - Restricted to the Gregorian calendar; non-Gregorian calendar variants
+ *   are out of scope for this function.
+ * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ *
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param style Optional name style: `"long"` (default), `"short"`, or `"narrow"`
+ * @returns 12-element array of month names in calendar order, or `[]` on invalid input
+ *
+ * @example getLocaleMonthNames("en-US") // ["January", "February", ... "December"]
+ * @example getLocaleMonthNames("de-DE", "short") // ["Jan", "Feb", "Mär", ... "Dez"]
+ * @example getLocaleMonthNames("fr-FR", "narrow") // ["J", "F", "M", ... "D"]
+ * @example getLocaleMonthNames("not-a-locale") // []
+ */
+export function getLocaleMonthNames(locale, style = "long") {
+    if (typeof locale !== "string")
+        return [];
+    try {
+        // Validate the BCP 47 tag; `Intl.Locale` throws on a syntactically
+        // invalid tag, which we map to the array sentinel.
+        new Intl.Locale(locale);
+    }
+    catch {
+        return [];
+    }
+    try {
+        const resolved = style === "short" || style === "narrow" ? style : "long";
+        const names = [];
+        for (let month = 1; month <= 12; month++) {
+            const date = Temporal.PlainDate.from(`2024-${String(month).padStart(2, "0")}-15`);
+            names.push(date.toLocaleString(locale, { month: resolved, calendar: "gregory" }));
+        }
+        return names;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/plain/locale/getLocaleWeekdayNames.d.ts

@@ -0,0 +1,25 @@
+import type { LocaleNameStyle } from "./getLocaleMonthNames.js";
+/**
+ * Return the 7 weekday names for a locale, ordered starting from the
+ * locale's first day of the week.
+ *
+ * - For `en-US` the array starts with Sunday; for `fr-FR` it starts with
+ *   Monday; for `ar-SA` it starts with Saturday — matching GMT's existing
+ *   locale-first-day convention in `getLocaleDayOfWeek` / `getLocaleStartOfWeek`.
+ * - This ordering is consistent with `getLocaleDayOfWeek`: for any valid
+ *   date, `getLocaleWeekdayNames(locale)[getLocaleDayOfWeek(date, locale)]`
+ *   is that date's localized weekday name.
+ * - Uses the host runtime's `Intl` data via `Temporal.PlainDate`, so output
+ *   depends on the runtime's ICU build.
+ * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ *
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param style Optional name style: `"long"` (default), `"short"`, or `"narrow"`
+ * @returns 7-element array of weekday names from the locale's first day, or `[]` on invalid input
+ *
+ * @example getLocaleWeekdayNames("en-US") // ["Sunday", "Monday", ... "Saturday"]
+ * @example getLocaleWeekdayNames("fr-FR") // ["lundi", "mardi", ... "dimanche"]
+ * @example getLocaleWeekdayNames("de-DE", "short") // ["Mo", "Di", "Mi", ... "So"]
+ * @example getLocaleWeekdayNames("not-a-locale") // []
+ */
+export declare function getLocaleWeekdayNames(locale: string, style?: LocaleNameStyle): string[];

package/dist/plain/locale/getLocaleWeekdayNames.js

@@ -0,0 +1,48 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
+/**
+ * Return the 7 weekday names for a locale, ordered starting from the
+ * locale's first day of the week.
+ *
+ * - For `en-US` the array starts with Sunday; for `fr-FR` it starts with
+ *   Monday; for `ar-SA` it starts with Saturday — matching GMT's existing
+ *   locale-first-day convention in `getLocaleDayOfWeek` / `getLocaleStartOfWeek`.
+ * - This ordering is consistent with `getLocaleDayOfWeek`: for any valid
+ *   date, `getLocaleWeekdayNames(locale)[getLocaleDayOfWeek(date, locale)]`
+ *   is that date's localized weekday name.
+ * - Uses the host runtime's `Intl` data via `Temporal.PlainDate`, so output
+ *   depends on the runtime's ICU build.
+ * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ *
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param style Optional name style: `"long"` (default), `"short"`, or `"narrow"`
+ * @returns 7-element array of weekday names from the locale's first day, or `[]` on invalid input
+ *
+ * @example getLocaleWeekdayNames("en-US") // ["Sunday", "Monday", ... "Saturday"]
+ * @example getLocaleWeekdayNames("fr-FR") // ["lundi", "mardi", ... "dimanche"]
+ * @example getLocaleWeekdayNames("de-DE", "short") // ["Mo", "Di", "Mi", ... "So"]
+ * @example getLocaleWeekdayNames("not-a-locale") // []
+ */
+export function getLocaleWeekdayNames(locale, style = "long") {
+    if (typeof locale !== "string")
+        return [];
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    if (firstDay === null)
+        return [];
+    try {
+        const resolved = style === "short" || style === "narrow" ? style : "long";
+        // Build the names in ISO order (Monday-first), then rotate so the
+        // locale's first day of week sits at index 0.
+        const isoOrder = [];
+        for (let dayOfWeek = 1; dayOfWeek <= 7; dayOfWeek++) {
+            const date = Temporal.PlainDate.from("2024-01-15").add({
+                days: dayOfWeek - 1,
+            });
+            isoOrder.push(date.toLocaleString(locale, { weekday: resolved }));
+        }
+        return isoOrder.slice(firstDay - 1).concat(isoOrder.slice(0, firstDay - 1));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/plain/locale/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./getLocaleEraNames.js";
+export * from "./getLocaleMeridiems.js";
+export * from "./getLocaleMonthNames.js";
+export * from "./getLocaleWeekdayNames.js";

package/dist/plain/locale/index.js

@@ -0,0 +1,4 @@
+export * from "./getLocaleEraNames.js";
+export * from "./getLocaleMeridiems.js";
+export * from "./getLocaleMonthNames.js";
+export * from "./getLocaleWeekdayNames.js";

package/dist/plain/map/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./mapDatesInRange.js";
+export * from "./mapDaysInMonth.js";

package/dist/plain/map/index.js

@@ -0,0 +1,2 @@
+export * from "./mapDatesInRange.js";
+export * from "./mapDaysInMonth.js";

package/dist/plain/map/mapDatesInRange.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ *
+ * @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
+ * @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("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-05", 0) // []
+ */
+export declare function mapDatesInRange(startDate: string, endDate: string, ...stepDaysInput: [stepDays?: number]): string[];

package/dist/plain/map/mapDatesInRange.js

@@ -0,0 +1,46 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.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.
+ *
+ * @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
+ * @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("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-05", 0) // []
+ */
+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 [];
+    }
+    try {
+        const start = Temporal.PlainDate.from(startDate);
+        const end = Temporal.PlainDate.from(endDate);
+        if (Temporal.PlainDate.compare(start, end) === 1) {
+            return [];
+        }
+        const result = [];
+        for (let current = start; Temporal.PlainDate.compare(current, end) <= 0; current = current.add({ days: resolvedStepDays })) {
+            result.push(current.toString());
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/plain/map/mapDaysInMonth.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return an array of ISO PlainDate strings for every day in the given year-month.
+ *
+ * - Generates array of dates for the specified month.
+ * - Validates input matches the year-month format exactly.
+ * - Returns [] for invalid input.
+ *
+ * @param month ISO PlainYearMonth string (YYYY-MM)
+ * @returns array of ISO PlainDate strings for each day in the month
+ *
+ * @example mapDaysInMonth("2024-02") // ["2024-02-01", "2024-02-02", ..., "2024-02-29"]
+ * @example mapDaysInMonth("2024-04") // ["2024-04-01", "2024-04-02", ..., "2024-04-30"]
+ * @example mapDaysInMonth("invalid") // []
+ */
+export declare function mapDaysInMonth(month: string): string[];

package/dist/plain/map/mapDaysInMonth.js

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return an array of ISO PlainDate strings for every day in the given year-month.
+ *
+ * - Generates array of dates for the specified month.
+ * - Validates input matches the year-month format exactly.
+ * - Returns [] for invalid input.
+ *
+ * @param month ISO PlainYearMonth string (YYYY-MM)
+ * @returns array of ISO PlainDate strings for each day in the month
+ *
+ * @example mapDaysInMonth("2024-02") // ["2024-02-01", "2024-02-02", ..., "2024-02-29"]
+ * @example mapDaysInMonth("2024-04") // ["2024-04-01", "2024-04-02", ..., "2024-04-30"]
+ * @example mapDaysInMonth("invalid") // []
+ */
+export function mapDaysInMonth(month) {
+    try {
+        const yearMonth = Temporal.PlainYearMonth.from(month);
+        if (yearMonth.toString() !== month) {
+            return [];
+        }
+        const daysInMonth = yearMonth.daysInMonth;
+        return Array.from({ length: daysInMonth }, (_, index) => {
+            const day = (index + 1).toString().padStart(2, "0");
+            return `${yearMonth.toString()}-${day}`;
+        });
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,29 @@
+export * from "./parseDayFromDate.js";
+export * from "./parseDayFromDateTime.js";
+export * from "./parseDayOfWeekFromDate.js";
+export * from "./parseDayOfWeekFromDateTime.js";
+export * from "./parseDateTimeWithPattern.js";
+export * from "./parseDateWithPattern.js";
+export * from "./parseHourFromDateTime.js";
+export * from "./parseHourFromTime.js";
+export * from "./parseMicrosecondFromDateTime.js";
+export * from "./parseMicrosecondFromTime.js";
+export * from "./parseMillisecondFromDateTime.js";
+export * from "./parseMillisecondFromTime.js";
+export * from "./parseMinuteFromDateTime.js";
+export * from "./parseMinuteFromTime.js";
+export * from "./parseMonthFromDate.js";
+export * from "./parseMonthFromDateTime.js";
+export * from "./parseNanosecondFromDateTime.js";
+export * from "./parseNanosecondFromTime.js";
+export * from "./parseSecondFromDateTime.js";
+export * from "./parseSecondFromTime.js";
+export * from "./parseSql.js";
+export * from "./parseTimeWithPattern.js";
+export * from "./parseUnitFromDate.js";
+export * from "./parseUnitFromDateTime.js";
+export * from "./parseUnitFromTime.js";
+export * from "./parseWeekFromDate.js";
+export * from "./parseWeekFromDateTime.js";
+export * from "./parseYearFromDate.js";
+export * from "./parseYearFromDateTime.js";

package/dist/plain/parse/index.js

@@ -0,0 +1,29 @@
+export * from "./parseDayFromDate.js";
+export * from "./parseDayFromDateTime.js";
+export * from "./parseDayOfWeekFromDate.js";
+export * from "./parseDayOfWeekFromDateTime.js";
+export * from "./parseDateTimeWithPattern.js";
+export * from "./parseDateWithPattern.js";
+export * from "./parseHourFromDateTime.js";
+export * from "./parseHourFromTime.js";
+export * from "./parseMicrosecondFromDateTime.js";
+export * from "./parseMicrosecondFromTime.js";
+export * from "./parseMillisecondFromDateTime.js";
+export * from "./parseMillisecondFromTime.js";
+export * from "./parseMinuteFromDateTime.js";
+export * from "./parseMinuteFromTime.js";
+export * from "./parseMonthFromDate.js";
+export * from "./parseMonthFromDateTime.js";
+export * from "./parseNanosecondFromDateTime.js";
+export * from "./parseNanosecondFromTime.js";
+export * from "./parseSecondFromDateTime.js";
+export * from "./parseSecondFromTime.js";
+export * from "./parseSql.js";
+export * from "./parseTimeWithPattern.js";
+export * from "./parseUnitFromDate.js";
+export * from "./parseUnitFromDateTime.js";
+export * from "./parseUnitFromTime.js";
+export * from "./parseWeekFromDate.js";
+export * from "./parseWeekFromDateTime.js";
+export * from "./parseYearFromDate.js";
+export * from "./parseYearFromDateTime.js";

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

@@ -0,0 +1,85 @@
+/**
+ * Parse a datetime string against a caller-supplied token pattern (e.g.
+ * `"MM/dd/yyyy HH:mm:ss"`, `"dd-MMM-yyyy h:mm a"`) and return it as an
+ * ISO `PlainDateTime` string.
+ *
+ * - **Decoding, not display.** This is for consuming a *known, fixed*
+ *   producer format — a CSV column, a legacy API field, a partially-typed
+ *   form value — not for generating locale-correct output. For display,
+ *   use `formatDateTime`/`formatDateToParts`, which order fields per
+ *   locale instead of hard-coding a field order (see roadmap Decision 1
+ *   — a token *formatter*, the inverse of this function, is deliberately
+ *   out of scope for GMT).
+ * - Accepts the full combined date + time token set (unlike
+ *   `parseDateWithPattern`/`parseTimeWithPattern`, which each reject the
+ *   other's tokens).
+ *
+ * ### Token table
+ * | Token | Field | Width | Range | Notes |
+ * |---|---|---|---|---|
+ * | `yyyy` | year | 4 digits | 0000–9999 | |
+ * | `yy` | year | 2 digits | 00–99 | Pivot: 00–68 → 2000–2068, 69–99 → 1969–1999 (fixed rule) |
+ * | `MM` | month | 2 digits | 01–12 | |
+ * | `M` | month | 1-2 digits | 1–12 | |
+ * | `MMMM` | month name (long) | locale | — | `getLocaleMonthNames(locale, "long")` |
+ * | `MMM` | month name (short) | locale | — | `getLocaleMonthNames(locale, "short")` |
+ * | `dd` | day | 2 digits | 01–31 | |
+ * | `d` | day | 1-2 digits | 1–31 | |
+ * | `HH` | hour (24h) | 2 digits | 00–23 | |
+ * | `H` | hour (24h) | 1-2 digits | 0–23 | |
+ * | `hh` | hour (12h) | 2 digits | 01–12 | needs `a` to resolve to 24h — see below |
+ * | `h` | hour (12h) | 1-2 digits | 1–12 | same |
+ * | `mm` | minute | 2 digits | 00–59 | |
+ * | `m` | minute | 1-2 digits | 0–59 | |
+ * | `ss` | second | 2 digits | 00–59 | |
+ * | `s` | second | 1-2 digits | 0–59 | |
+ * | `SSS` | millisecond | 3 digits | 000–999 | |
+ * | `EEEE` | weekday name (long) | locale | — | consumed, NOT cross-validated against the date (see below) |
+ * | `EEE` | weekday name (short) | locale | — | same |
+ * | `a` | meridiem | locale | — | `getLocaleMeridiems(locale)` → `[AM-label, PM-label]` |
+ * | `GGGG` | era name (long) | locale | — | BCE label ⇒ final year = 1 − parsed year |
+ * | `GG` | era name (short) | locale | — | same resolution |
+ *
+ * - Text in `'single quotes'` is a literal; a doubled `''` inside a
+ *   quoted segment is a literal `'`. Any other character (`/ - , space
+ *   :`, literal digits, etc.) outside a quote/letter-run is automatically
+ *   a literal — no explicit quoting required.
+ * - `MMMM`/`MMM`/`EEEE`/`EEE`/`a`/`GGGG`/`GG` are locale-aware. If
+ *   `locale` is omitted and the pattern uses any of them, GMT defaults
+ *   to `"en-US"` rather than returning `""` for every caller who didn't
+ *   have another locale in mind.
+ * - `EEEE`/`EEE` are matched against the locale's weekday names but the
+ *   result is **not** cross-checked against the constructed date — e.g.
+ *   `"Monday, 2024-03-15 14:00"` parses successfully against
+ *   `"EEEE, yyyy-MM-dd HH:mm"` even though 2024-03-15 is actually a
+ *   Friday. This is a deliberate scope limit (no second
+ *   weekday-index-to-ISO-dayOfWeek mapping layer).
+ * - `h`/`hh` resolve to 24-hour using a matched `a` token: if the label
+ *   is the PM label and hour !== 12, add 12; if the AM label and hour
+ *   === 12, set hour to 0. With no `a` token in the pattern at all, the
+ *   pattern is still valid but the hour stays ambiguous — GMT resolves
+ *   it as if AM had matched (12 → 0, otherwise unchanged).
+ * - Adjacent variable-width numeric tokens with no literal separator
+ *   (e.g. `"Mdyyyy"`) are inherently ambiguous: each becomes a greedy
+ *   `\d{1,2}`/etc. in sequence, so the split between fields depends on
+ *   regex backtracking, not on any documented rule. Prefer zero-padded
+ *   tokens (`MM`, `dd`) or an explicit separator for reliable parsing.
+ * - A shape-valid match does not by itself prove a real date/time:
+ *   extracted fields are always handed to
+ *   `Temporal.PlainDateTime.from(fields, { overflow: "reject" })` — the
+ *   regex only proves the shape, Temporal proves the value is real.
+ * - Fields absent from `pattern` default the way `Temporal.PlainDateTime.from`
+ *   defaults an omitted field (time fields default to `0`; `year`/`month`/`day`
+ *   are still required for a valid result).
+ *
+ * @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")
+ * @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") // ""
+ */
+export declare function parseDateTimeWithPattern(value: string, pattern: string, locale?: string): string;

package/dist/plain/parse/parseDateTimeWithPattern.js

@@ -0,0 +1,116 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal/index.js";
+/**
+ * Parse a datetime string against a caller-supplied token pattern (e.g.
+ * `"MM/dd/yyyy HH:mm:ss"`, `"dd-MMM-yyyy h:mm a"`) and return it as an
+ * ISO `PlainDateTime` string.
+ *
+ * - **Decoding, not display.** This is for consuming a *known, fixed*
+ *   producer format — a CSV column, a legacy API field, a partially-typed
+ *   form value — not for generating locale-correct output. For display,
+ *   use `formatDateTime`/`formatDateToParts`, which order fields per
+ *   locale instead of hard-coding a field order (see roadmap Decision 1
+ *   — a token *formatter*, the inverse of this function, is deliberately
+ *   out of scope for GMT).
+ * - Accepts the full combined date + time token set (unlike
+ *   `parseDateWithPattern`/`parseTimeWithPattern`, which each reject the
+ *   other's tokens).
+ *
+ * ### Token table
+ * | Token | Field | Width | Range | Notes |
+ * |---|---|---|---|---|
+ * | `yyyy` | year | 4 digits | 0000–9999 | |
+ * | `yy` | year | 2 digits | 00–99 | Pivot: 00–68 → 2000–2068, 69–99 → 1969–1999 (fixed rule) |
+ * | `MM` | month | 2 digits | 01–12 | |
+ * | `M` | month | 1-2 digits | 1–12 | |
+ * | `MMMM` | month name (long) | locale | — | `getLocaleMonthNames(locale, "long")` |
+ * | `MMM` | month name (short) | locale | — | `getLocaleMonthNames(locale, "short")` |
+ * | `dd` | day | 2 digits | 01–31 | |
+ * | `d` | day | 1-2 digits | 1–31 | |
+ * | `HH` | hour (24h) | 2 digits | 00–23 | |
+ * | `H` | hour (24h) | 1-2 digits | 0–23 | |
+ * | `hh` | hour (12h) | 2 digits | 01–12 | needs `a` to resolve to 24h — see below |
+ * | `h` | hour (12h) | 1-2 digits | 1–12 | same |
+ * | `mm` | minute | 2 digits | 00–59 | |
+ * | `m` | minute | 1-2 digits | 0–59 | |
+ * | `ss` | second | 2 digits | 00–59 | |
+ * | `s` | second | 1-2 digits | 0–59 | |
+ * | `SSS` | millisecond | 3 digits | 000–999 | |
+ * | `EEEE` | weekday name (long) | locale | — | consumed, NOT cross-validated against the date (see below) |
+ * | `EEE` | weekday name (short) | locale | — | same |
+ * | `a` | meridiem | locale | — | `getLocaleMeridiems(locale)` → `[AM-label, PM-label]` |
+ * | `GGGG` | era name (long) | locale | — | BCE label ⇒ final year = 1 − parsed year |
+ * | `GG` | era name (short) | locale | — | same resolution |
+ *
+ * - Text in `'single quotes'` is a literal; a doubled `''` inside a
+ *   quoted segment is a literal `'`. Any other character (`/ - , space
+ *   :`, literal digits, etc.) outside a quote/letter-run is automatically
+ *   a literal — no explicit quoting required.
+ * - `MMMM`/`MMM`/`EEEE`/`EEE`/`a`/`GGGG`/`GG` are locale-aware. If
+ *   `locale` is omitted and the pattern uses any of them, GMT defaults
+ *   to `"en-US"` rather than returning `""` for every caller who didn't
+ *   have another locale in mind.
+ * - `EEEE`/`EEE` are matched against the locale's weekday names but the
+ *   result is **not** cross-checked against the constructed date — e.g.
+ *   `"Monday, 2024-03-15 14:00"` parses successfully against
+ *   `"EEEE, yyyy-MM-dd HH:mm"` even though 2024-03-15 is actually a
+ *   Friday. This is a deliberate scope limit (no second
+ *   weekday-index-to-ISO-dayOfWeek mapping layer).
+ * - `h`/`hh` resolve to 24-hour using a matched `a` token: if the label
+ *   is the PM label and hour !== 12, add 12; if the AM label and hour
+ *   === 12, set hour to 0. With no `a` token in the pattern at all, the
+ *   pattern is still valid but the hour stays ambiguous — GMT resolves
+ *   it as if AM had matched (12 → 0, otherwise unchanged).
+ * - Adjacent variable-width numeric tokens with no literal separator
+ *   (e.g. `"Mdyyyy"`) are inherently ambiguous: each becomes a greedy
+ *   `\d{1,2}`/etc. in sequence, so the split between fields depends on
+ *   regex backtracking, not on any documented rule. Prefer zero-padded
+ *   tokens (`MM`, `dd`) or an explicit separator for reliable parsing.
+ * - A shape-valid match does not by itself prove a real date/time:
+ *   extracted fields are always handed to
+ *   `Temporal.PlainDateTime.from(fields, { overflow: "reject" })` — the
+ *   regex only proves the shape, Temporal proves the value is real.
+ * - Fields absent from `pattern` default the way `Temporal.PlainDateTime.from`
+ *   defaults an omitted field (time fields default to `0`; `year`/`month`/`day`
+ *   are still required for a valid result).
+ *
+ * @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")
+ * @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") // ""
+ */
+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();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Parse a date string against a caller-supplied token pattern (e.g.
+ * `"MM/dd/yyyy"`, `"dd-MMM-yyyy"`) and return it as an ISO `PlainDate`
+ * string.
+ *
+ * - **Decoding, not display.** This is for consuming a *known, fixed*
+ *   producer format — a CSV column, a legacy API field, a partially-typed
+ *   form value — not for generating locale-correct output. For display,
+ *   use `formatDate`/`formatDateToParts`, which order fields per locale
+ *   instead of hard-coding a field order (see roadmap Decision 1 — a
+ *   token *formatter*, the inverse of this function, is deliberately out
+ *   of scope for GMT).
+ * - `pattern` accepts only date-shaped tokens. A pattern containing a
+ *   time-only token (`H h m s S a`) is malformed for this function and
+ *   returns `""` — use `parseDateTimeWithPattern` for combined input.
+ *
+ * ### Token table
+ * | Token | Field | Width | Range | Notes |
+ * |---|---|---|---|---|
+ * | `yyyy` | year | 4 digits | 0000–9999 | |
+ * | `yy` | year | 2 digits | 00–99 | Pivot: 00–68 → 2000–2068, 69–99 → 1969–1999 (fixed rule) |
+ * | `MM` | month | 2 digits | 01–12 | |
+ * | `M` | month | 1-2 digits | 1–12 | |
+ * | `MMMM` | month name (long) | locale | — | `getLocaleMonthNames(locale, "long")` |
+ * | `MMM` | month name (short) | locale | — | `getLocaleMonthNames(locale, "short")` |
+ * | `dd` | day | 2 digits | 01–31 | |
+ * | `d` | day | 1-2 digits | 1–31 | |
+ * | `EEEE` | weekday name (long) | locale | — | consumed, NOT cross-validated against the date (see below) |
+ * | `EEE` | weekday name (short) | locale | — | same |
+ * | `GGGG` | era name (long) | locale | — | BCE label ⇒ final year = 1 − parsed year |
+ * | `GG` | era name (short) | locale | — | same resolution |
+ *
+ * - Text in `'single quotes'` is a literal; a doubled `''` inside a
+ *   quoted segment is a literal `'`. Any other character (`/ - , space`,
+ *   literal digits, etc.) outside a quote/letter-run is automatically a
+ *   literal — no explicit quoting required.
+ * - `MMMM`/`MMM`/`EEEE`/`EEE`/`GGGG`/`GG` are locale-aware. If `locale`
+ *   is omitted and the pattern uses any of them, GMT defaults to
+ *   `"en-US"` rather than returning `""` for every caller who didn't
+ *   have another locale in mind — pass `locale` explicitly for others.
+ * - `EEEE`/`EEE` are matched against the locale's weekday names but the
+ *   result is **not** cross-checked against the constructed date — e.g.
+ *   `"Monday, 2024-03-15"` parses successfully against
+ *   `"EEEE, yyyy-MM-dd"` even though 2024-03-15 is actually a Friday.
+ *   This is a deliberate scope limit (no second weekday-index-to-ISO-
+ *   dayOfWeek mapping layer).
+ * - Adjacent variable-width numeric tokens with no literal separator
+ *   (e.g. `"Mdyyyy"`) are inherently ambiguous: each becomes a greedy
+ *   `\d{1,2}`/etc. in sequence, so the split between fields depends on
+ *   regex backtracking, not on any documented rule. Prefer zero-padded
+ *   tokens (`MM`, `dd`) or an explicit separator for reliable parsing.
+ * - A shape-valid match does not by itself prove a real date: extracted
+ *   fields are always handed to `Temporal.PlainDate.from(fields, {
+ *   overflow: "reject" })`, so `"02/31/2024"` against `"MM/dd/yyyy"`
+ *   still returns `""` — the regex only proves the shape, Temporal
+ *   proves the date is real.
+ *
+ * @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")
+ * @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)
+ */
+export declare function parseDateWithPattern(value: string, pattern: string, locale?: string): string;