@northguild/gmt 1.18.0 → 1.19.0

package/dist/plain/format/formatCalendar.js

@@ -4,6 +4,7 @@ import { joinDateTimeConnector, normalizeDateTime } from "../../internal/index.j
 import { plainTimeStyle } from "../../internal/plainFormatOptions.js";
 import { isValidDateTime } from "../validate/index.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
+import { isObject } from "../../internal/isObject.js";
 // GMT's own rule, not a standard's: the relative day label is kept for distances
 // under one week (up to 6 calendar days either way). From 7 days out the phrase
 // is an absolute date, which is easier to place than a day count.
@@ -51,7 +52,7 @@ export function formatCalendar(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
         // invalid input.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidDateTime(value))
             return "";

package/dist/plain/format/formatRelativeDate.js

@@ -3,6 +3,7 @@ import { durationTotal } from "../../internal/index.js";
 import { formatRelativeAmount } from "../../internal/formatRelativeDuration.js";
 import { isValidDate } from "../validate/index.js";
 import { resolveRelativeUnit } from "../../internal/resolveRelativeUnit.js";
+import { isObject } from "../../internal/isObject.js";
 // Temporal's date unit group: the units a PlainDate difference may be written in.
 const DATE_UNITS = [
     "year",
@@ -40,7 +41,7 @@ export function formatRelativeDate(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
         // invalid input.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidDate(value))
             return "";

package/dist/plain/format/formatRelativeDateTime.js

@@ -3,6 +3,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { durationTotal } from "../../internal/index.js";
 import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js";
 import { isValidDateTime } from "../validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Format the relative time between a plain date-time and a reference date-time.
  *
@@ -33,7 +34,7 @@ export function formatRelativeDateTime(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
         // invalid input.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidDateTime(value))
             return "";

package/dist/plain/format/formatRelativeTime.js

@@ -2,6 +2,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { formatRelativeAmount } from "../../internal/formatRelativeDuration.js";
 import { isValidTime } from "../validate/index.js";
 import { resolveRelativeUnit } from "../../internal/resolveRelativeUnit.js";
+import { isObject } from "../../internal/isObject.js";
 // Temporal's time unit group down to the second: the units a PlainTime difference may be written
 // in, less the sub-second units, which Intl.RelativeTimeFormat does not have.
 const TIME_UNITS = [
@@ -38,7 +39,7 @@ export function formatRelativeTime(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
         // invalid input.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidTime(value))
             return "";

package/dist/plain/format/{formatSql.d.ts → formatSqlDateTime.d.ts}

@@ -3,7 +3,7 @@
  * `YYYY-MM-DD HH:MM:SS[.fff]` form of standard SQL `TIMESTAMP` and MySQL/SQLite `DATETIME`
  * columns.
  *
- * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, which `parseSql`
+ * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, which `parseSqlDateTime`
  *   reads: the date, a single space, and the time with seconds always written.
  * - A year outside SQL-92's `0001`–`9999` (Table 10) returns `""`: the literal has no sign and
  *   no expanded year to write it with.
@@ -16,10 +16,10 @@
  * @param value plain ISO 8601 datetime string (e.g. "2024-03-15T14:30:00")
  * @returns SQL timestamp literal, or "" on invalid input
  *
- * @example formatSql("2024-03-15T14:30:00") // "2024-03-15 14:30:00"
- * @example formatSql("2024-03-15T14:30") // "2024-03-15 14:30:00"
- * @example formatSql("2024-03-15T14:30:00.500") // "2024-03-15 14:30:00.5"
- * @example formatSql("0000-01-01T00:00:00") // "" (year outside 0001–9999)
- * @example formatSql("invalid") // ""
+ * @example formatSqlDateTime("2024-03-15T14:30:00") // "2024-03-15 14:30:00"
+ * @example formatSqlDateTime("2024-03-15T14:30") // "2024-03-15 14:30:00"
+ * @example formatSqlDateTime("2024-03-15T14:30:00.500") // "2024-03-15 14:30:00.5"
+ * @example formatSqlDateTime("0000-01-01T00:00:00") // "" (year outside 0001–9999)
+ * @example formatSqlDateTime("invalid") // ""
  */
-export declare function formatSql(value: string): string;
+export declare function formatSqlDateTime(value: string): string;

package/dist/plain/format/{formatSql.js → formatSqlDateTime.js}

@@ -5,7 +5,7 @@ import { isValidDateTime } from "../validate/index.js";
  * `YYYY-MM-DD HH:MM:SS[.fff]` form of standard SQL `TIMESTAMP` and MySQL/SQLite `DATETIME`
  * columns.
  *
- * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, which `parseSql`
+ * - **Grammar:** SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape, which `parseSqlDateTime`
  *   reads: the date, a single space, and the time with seconds always written.
  * - A year outside SQL-92's `0001`–`9999` (Table 10) returns `""`: the literal has no sign and
  *   no expanded year to write it with.
@@ -18,13 +18,13 @@ import { isValidDateTime } from "../validate/index.js";
  * @param value plain ISO 8601 datetime string (e.g. "2024-03-15T14:30:00")
  * @returns SQL timestamp literal, or "" on invalid input
  *
- * @example formatSql("2024-03-15T14:30:00") // "2024-03-15 14:30:00"
- * @example formatSql("2024-03-15T14:30") // "2024-03-15 14:30:00"
- * @example formatSql("2024-03-15T14:30:00.500") // "2024-03-15 14:30:00.5"
- * @example formatSql("0000-01-01T00:00:00") // "" (year outside 0001–9999)
- * @example formatSql("invalid") // ""
+ * @example formatSqlDateTime("2024-03-15T14:30:00") // "2024-03-15 14:30:00"
+ * @example formatSqlDateTime("2024-03-15T14:30") // "2024-03-15 14:30:00"
+ * @example formatSqlDateTime("2024-03-15T14:30:00.500") // "2024-03-15 14:30:00.5"
+ * @example formatSqlDateTime("0000-01-01T00:00:00") // "" (year outside 0001–9999)
+ * @example formatSqlDateTime("invalid") // ""
  */
-export function formatSql(value) {
+export function formatSqlDateTime(value) {
     if (!isValidDateTime(value))
         return "";
     try {

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

@@ -8,5 +8,5 @@ export * from "./formatDateToParts.js";
 export * from "./formatRelativeDate.js";
 export * from "./formatRelativeDateTime.js";
 export * from "./formatRelativeTime.js";
-export * from "./formatSql.js";
+export * from "./formatSqlDateTime.js";
 export * from "./formatTime.js";

package/dist/plain/format/index.js

@@ -8,5 +8,5 @@ export * from "./formatDateToParts.js";
 export * from "./formatRelativeDate.js";
 export * from "./formatRelativeDateTime.js";
 export * from "./formatRelativeTime.js";
-export * from "./formatSql.js";
+export * from "./formatSqlDateTime.js";
 export * from "./formatTime.js";

package/dist/plain/get/getNowUnit.d.ts

@@ -8,6 +8,8 @@ export type { NowUnit };
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
  * - Returns "" when unit is invalid or system timezone is unavailable.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param unit unit to extract from current local time
  * @returns string representation of the requested unit or "" on invalid

package/dist/plain/get/getNowUnit.js

@@ -15,6 +15,8 @@ function isValidPlainNowUnit(unit) {
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
  * - Returns "" when unit is invalid or system timezone is unavailable.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param unit unit to extract from current local time
  * @returns string representation of the requested unit or "" on invalid

package/dist/plain/get/getYear.d.ts

@@ -3,6 +3,8 @@
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get current year in system timezone.
  * - Returns zero-padded string (e.g., "2024").
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it at the head of a date.
  * - Returns "" when system timezone is unavailable.
  *
  * @returns current year string (zero-padded) or "" on invalid

package/dist/plain/get/getYear.js

@@ -1,10 +1,13 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { getSystemTimeZone } from "../../zoned/get/getSystemTimeZone.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Return the current year as a zero-padded string in the system timeZone.
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get current year in system timezone.
  * - Returns zero-padded string (e.g., "2024").
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it at the head of a date.
  * - Returns "" when system timezone is unavailable.
  *
  * @returns current year string (zero-padded) or "" on invalid
@@ -17,9 +20,7 @@ export function getYear() {
     if (!timeZone)
         return "";
     try {
-        return Temporal.Now.zonedDateTimeISO(timeZone)
-            .year.toString()
-            .padStart(4, "0");
+        return isoYearString(Temporal.Now.zonedDateTimeISO(timeZone).year);
     }
     catch {
         return "";

package/dist/plain/interval/intervalXorAllDate.js

@@ -2,6 +2,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { calendarOfAllDateValues, formatDateInCalendar, halfOpenXor, parseCalendarDateValue, } from "../../internal/index.js";
 import { isValidDateInterval } from "./validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Return the symmetric difference across a list of date intervals — the set of dates covered
  * by an odd number of the input intervals.
@@ -36,8 +37,7 @@ export function intervalXorAllDate(intervals) {
         if (!Array.isArray(intervals) || intervals.length === 0) {
             return [];
         }
-        if (!intervals.every((interval) => interval &&
-            typeof interval === "object" &&
+        if (!intervals.every((interval) => isObject(interval) &&
             isValidDateInterval(interval.start, interval.end))) {
             return [];
         }

package/dist/plain/interval/intervalXorAllDateTime.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { halfOpenXor } from "../../internal/index.js";
 import { isValidDateTimeInterval } from "./validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Return the symmetric difference across a list of datetime intervals — the set of instants
  * covered by an odd number of the input intervals.
@@ -30,8 +31,7 @@ export function intervalXorAllDateTime(intervals) {
         if (!Array.isArray(intervals) || intervals.length === 0) {
             return [];
         }
-        if (!intervals.every((interval) => interval &&
-            typeof interval === "object" &&
+        if (!intervals.every((interval) => isObject(interval) &&
             isValidDateTimeInterval(interval.start, interval.end))) {
             return [];
         }

package/dist/plain/interval/intervalXorAllTime.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { halfOpenXor } from "../../internal/index.js";
 import { isValidTimeInterval } from "./validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Return the symmetric difference across a list of time intervals — the set of clock times
  * covered by an odd number of the input intervals.
@@ -31,8 +32,7 @@ export function intervalXorAllTime(intervals) {
         if (!Array.isArray(intervals) || intervals.length === 0) {
             return [];
         }
-        if (!intervals.every((interval) => interval &&
-            typeof interval === "object" &&
+        if (!intervals.every((interval) => isObject(interval) &&
             isValidTimeInterval(interval.start, interval.end))) {
             return [];
         }

package/dist/plain/interval/mergeIntervalsDate.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { calendarOfAllDateValues, formatDateInCalendar, halfOpenMerge, parseCalendarDateValue, } from "../../internal/index.js";
 import { isValidDateInterval } from "./validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Collapse a list of date intervals into the minimum set of non-overlapping intervals.
  *
@@ -34,8 +35,7 @@ export function mergeIntervalsDate(intervals) {
         if (!Array.isArray(intervals) || intervals.length === 0) {
             return [];
         }
-        if (!intervals.every((interval) => interval &&
-            typeof interval === "object" &&
+        if (!intervals.every((interval) => isObject(interval) &&
             isValidDateInterval(interval.start, interval.end))) {
             return [];
         }

package/dist/plain/interval/mergeIntervalsDateTime.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { halfOpenMerge } from "../../internal/index.js";
 import { isValidDateTimeInterval } from "./validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Collapse a list of datetime intervals into the minimum set of non-overlapping intervals.
  *
@@ -29,8 +30,7 @@ export function mergeIntervalsDateTime(intervals) {
         if (!Array.isArray(intervals) || intervals.length === 0) {
             return [];
         }
-        if (!intervals.every((interval) => interval &&
-            typeof interval === "object" &&
+        if (!intervals.every((interval) => isObject(interval) &&
             isValidDateTimeInterval(interval.start, interval.end))) {
             return [];
         }

package/dist/plain/interval/mergeIntervalsTime.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { halfOpenMerge } from "../../internal/index.js";
 import { isValidTimeInterval } from "./validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Collapse a list of time intervals into the minimum set of non-overlapping intervals.
  *
@@ -29,8 +30,7 @@ export function mergeIntervalsTime(intervals) {
         if (!Array.isArray(intervals) || intervals.length === 0) {
             return [];
         }
-        if (!intervals.every((interval) => interval &&
-            typeof interval === "object" &&
+        if (!intervals.every((interval) => isObject(interval) &&
             isValidTimeInterval(interval.start, interval.end))) {
             return [];
         }

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

@@ -18,7 +18,7 @@ export * from "./parseNanosecondFromDateTime.js";
 export * from "./parseNanosecondFromTime.js";
 export * from "./parseSecondFromDateTime.js";
 export * from "./parseSecondFromTime.js";
-export * from "./parseSql.js";
+export * from "./parseSqlDateTime.js";
 export * from "./parseTimeWithPattern.js";
 export * from "./parseUnitFromDate.js";
 export * from "./parseUnitFromDateTime.js";

package/dist/plain/parse/index.js

@@ -18,7 +18,7 @@ export * from "./parseNanosecondFromDateTime.js";
 export * from "./parseNanosecondFromTime.js";
 export * from "./parseSecondFromDateTime.js";
 export * from "./parseSecondFromTime.js";
-export * from "./parseSql.js";
+export * from "./parseSqlDateTime.js";
 export * from "./parseTimeWithPattern.js";
 export * from "./parseUnitFromDate.js";
 export * from "./parseUnitFromDateTime.js";

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

@@ -1,3 +1,4 @@
+import type { TwoDigitYearOptions } from "../../types/two-digit-year.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
@@ -17,7 +18,7 @@
  * | 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) |
+ * | `yy` | year | 2 digits | 00–99 | Needs `options.yearWindow`; returns `""` without it |
  * | `MM` | month | 2 digits | 01–12 | |
  * | `M` | month | 1-2 digits | 1–12 | |
  * | `MMMM` | month name (long) | locale | — | `getLocaleMonthNames(locale, "long")` |
@@ -73,17 +74,29 @@
  * - 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).
+ * - A `yy` token needs the caller's hundred-year window,
+ *   `options.yearWindow`: no standard says which century a two-digit
+ *   year belongs to, and a cut-off built into a library is right today
+ *   and wrong later. Without a valid window a `yy` pattern returns `""`.
+ *   A pattern with no `yy` never reads the option, so a `"rolling"`
+ *   window reads no clock for it. A two-digit year is a legacy form; a
+ *   four-digit year is the one to ask a data source for.
  *
  * @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 tag, or a preference list of tags, for name-based tokens (default "en-US")
+ * @param options The hundred-year window a `yy` token resolves in
  * @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("Mar 15, '24 at 14:30", "MMM d, ''yy 'at' HH:mm") // "2024-03-15T14:30:00" ('' is one literal quote)
+ * @example parseDateTimeWithPattern("Mar 15, '24 at 14:30", "MMM d, ''yy 'at' HH:mm", undefined, { yearWindow: 2000 }) // "2024-03-15T14:30:00" ('' is one literal quote)
+ * @example parseDateTimeWithPattern("99-03-15 14:30", "yy-MM-dd HH:mm", undefined, { yearWindow: 1950 }) // "1999-03-15T14:30:00" (1950–2049 window)
+ * @example parseDateTimeWithPattern("24-03-15 14:30", "yy-MM-dd HH:mm", undefined, { yearWindow: "rolling" }) // "2024-03-15T14:30:00" (while the current UTC year is 1975–2074)
+ * @example parseDateTimeWithPattern("24-03-15 14:30", "yy-MM-dd HH:mm") // "" (yy with no window)
+ * @example parseDateTimeWithPattern("03/15/2024 14:30:00", "MM/dd/yyyy HH:mm:ss", undefined, { yearWindow: 2000 }) // "2024-03-15T14:30:00" (yyyy ignores the window)
  * @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[]): string;
+export declare function parseDateTimeWithPattern(value: string, pattern: string, locale?: string | string[], options?: TwoDigitYearOptions): string;

package/dist/plain/parse/parseDateTimeWithPattern.js

@@ -1,5 +1,6 @@
+// fallow-ignore-file code-duplication -- sibling of parseDateWithPattern; each keeps its own guard, options check and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal/index.js";
+import { DATE_TIME_PATTERN_FIELDS, isOptionsArgument, 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
@@ -19,7 +20,7 @@ import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal
  * | 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) |
+ * | `yy` | year | 2 digits | 00–99 | Needs `options.yearWindow`; returns `""` without it |
  * | `MM` | month | 2 digits | 01–12 | |
  * | `M` | month | 1-2 digits | 1–12 | |
  * | `MMMM` | month name (long) | locale | — | `getLocaleMonthNames(locale, "long")` |
@@ -75,26 +76,40 @@ import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal
  * - 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).
+ * - A `yy` token needs the caller's hundred-year window,
+ *   `options.yearWindow`: no standard says which century a two-digit
+ *   year belongs to, and a cut-off built into a library is right today
+ *   and wrong later. Without a valid window a `yy` pattern returns `""`.
+ *   A pattern with no `yy` never reads the option, so a `"rolling"`
+ *   window reads no clock for it. A two-digit year is a legacy form; a
+ *   four-digit year is the one to ask a data source for.
  *
  * @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 tag, or a preference list of tags, for name-based tokens (default "en-US")
+ * @param options The hundred-year window a `yy` token resolves in
  * @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("Mar 15, '24 at 14:30", "MMM d, ''yy 'at' HH:mm") // "2024-03-15T14:30:00" ('' is one literal quote)
+ * @example parseDateTimeWithPattern("Mar 15, '24 at 14:30", "MMM d, ''yy 'at' HH:mm", undefined, { yearWindow: 2000 }) // "2024-03-15T14:30:00" ('' is one literal quote)
+ * @example parseDateTimeWithPattern("99-03-15 14:30", "yy-MM-dd HH:mm", undefined, { yearWindow: 1950 }) // "1999-03-15T14:30:00" (1950–2049 window)
+ * @example parseDateTimeWithPattern("24-03-15 14:30", "yy-MM-dd HH:mm", undefined, { yearWindow: "rolling" }) // "2024-03-15T14:30:00" (while the current UTC year is 1975–2074)
+ * @example parseDateTimeWithPattern("24-03-15 14:30", "yy-MM-dd HH:mm") // "" (yy with no window)
+ * @example parseDateTimeWithPattern("03/15/2024 14:30:00", "MM/dd/yyyy HH:mm:ss", undefined, { yearWindow: 2000 }) // "2024-03-15T14:30:00" (yyyy ignores the window)
  * @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) {
+export function parseDateTimeWithPattern(value, pattern, locale, options) {
     try {
         if (typeof value !== "string")
             return "";
         if (typeof pattern !== "string")
             return "";
-        const fields = parseValueWithPattern(value, pattern, locale, DATE_TIME_PATTERN_FIELDS);
+        if (!isOptionsArgument(options))
+            return "";
+        const fields = parseValueWithPattern(value, pattern, locale, DATE_TIME_PATTERN_FIELDS, options);
         if (fields === null)
             return "";
         try {

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

@@ -1,3 +1,4 @@
+import type { TwoDigitYearOptions } from "../../types/two-digit-year.js";
 /**
  * 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`
@@ -17,7 +18,7 @@
  * | 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) |
+ * | `yy` | year | 2 digits | 00–99 | Needs `options.yearWindow`; returns `""` without it |
  * | `MM` | month | 2 digits | 01–12 | |
  * | `M` | month | 1-2 digits | 1–12 | |
  * | `MMMM` | month name (long) | locale | — | `getLocaleMonthNames(locale, "long")` |
@@ -56,17 +57,30 @@
  *   overflow: "reject" })`, so `"02/31/2024"` against `"MM/dd/yyyy"`
  *   still returns `""` — the regex only proves the shape, Temporal
  *   proves the date is real.
+ * - A `yy` token needs the caller's hundred-year window,
+ *   `options.yearWindow`: no standard says which century a two-digit
+ *   year belongs to, and a cut-off built into a library is right today
+ *   and wrong later. Without a valid window a `yy` pattern returns `""`.
+ *   A pattern with no `yy` never reads the option, so a `"rolling"`
+ *   window reads no clock for it. A two-digit year is a legacy form; a
+ *   four-digit year is the one to ask a data source for.
  *
  * @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 tag, or a preference list of tags, for name-based tokens (default "en-US")
+ * @param options The hundred-year window a `yy` token resolves in
  * @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("Mar 15, '24", "MMM d, ''yy") // "2024-03-15" ('' is one literal quote)
+ * @example parseDateWithPattern("Mar 15, '24", "MMM d, ''yy", undefined, { yearWindow: 2000 }) // "2024-03-15" ('' is one literal quote)
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy", undefined, { yearWindow: 1950 }) // "2024-03-15" (1950–2049 window)
+ * @example parseDateWithPattern("03/15/99", "MM/dd/yy", undefined, { yearWindow: 1950 }) // "1999-03-15"
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy", undefined, { yearWindow: "rolling" }) // "2024-03-15" (while the current UTC year is 1975–2074)
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy") // "" (yy with no window)
+ * @example parseDateWithPattern("03/15/2024", "MM/dd/yyyy", undefined, { yearWindow: 2000 }) // "2024-03-15" (yyyy ignores the window)
  * @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[]): string;
+export declare function parseDateWithPattern(value: string, pattern: string, locale?: string | string[], options?: TwoDigitYearOptions): string;

package/dist/plain/parse/parseDateWithPattern.js

@@ -1,5 +1,6 @@
+// fallow-ignore-file code-duplication -- sibling of parseDateTimeWithPattern; each keeps its own guard, options check and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index.js";
+import { DATE_PATTERN_FIELDS, isOptionsArgument, parseValueWithPattern, } from "../../internal/index.js";
 /**
  * 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`
@@ -19,7 +20,7 @@ import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index
  * | 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) |
+ * | `yy` | year | 2 digits | 00–99 | Needs `options.yearWindow`; returns `""` without it |
  * | `MM` | month | 2 digits | 01–12 | |
  * | `M` | month | 1-2 digits | 1–12 | |
  * | `MMMM` | month name (long) | locale | — | `getLocaleMonthNames(locale, "long")` |
@@ -58,26 +59,41 @@ import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index
  *   overflow: "reject" })`, so `"02/31/2024"` against `"MM/dd/yyyy"`
  *   still returns `""` — the regex only proves the shape, Temporal
  *   proves the date is real.
+ * - A `yy` token needs the caller's hundred-year window,
+ *   `options.yearWindow`: no standard says which century a two-digit
+ *   year belongs to, and a cut-off built into a library is right today
+ *   and wrong later. Without a valid window a `yy` pattern returns `""`.
+ *   A pattern with no `yy` never reads the option, so a `"rolling"`
+ *   window reads no clock for it. A two-digit year is a legacy form; a
+ *   four-digit year is the one to ask a data source for.
  *
  * @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 tag, or a preference list of tags, for name-based tokens (default "en-US")
+ * @param options The hundred-year window a `yy` token resolves in
  * @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("Mar 15, '24", "MMM d, ''yy") // "2024-03-15" ('' is one literal quote)
+ * @example parseDateWithPattern("Mar 15, '24", "MMM d, ''yy", undefined, { yearWindow: 2000 }) // "2024-03-15" ('' is one literal quote)
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy", undefined, { yearWindow: 1950 }) // "2024-03-15" (1950–2049 window)
+ * @example parseDateWithPattern("03/15/99", "MM/dd/yy", undefined, { yearWindow: 1950 }) // "1999-03-15"
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy", undefined, { yearWindow: "rolling" }) // "2024-03-15" (while the current UTC year is 1975–2074)
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy") // "" (yy with no window)
+ * @example parseDateWithPattern("03/15/2024", "MM/dd/yyyy", undefined, { yearWindow: 2000 }) // "2024-03-15" (yyyy ignores the window)
  * @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) {
+export function parseDateWithPattern(value, pattern, locale, options) {
     try {
         if (typeof value !== "string")
             return "";
         if (typeof pattern !== "string")
             return "";
-        const fields = parseValueWithPattern(value, pattern, locale, DATE_PATTERN_FIELDS);
+        if (!isOptionsArgument(options))
+            return "";
+        const fields = parseValueWithPattern(value, pattern, locale, DATE_PATTERN_FIELDS, options);
         if (fields === null)
             return "";
         try {

package/dist/plain/parse/{parseSql.d.ts → parseSqlDateTime.d.ts}

@@ -8,7 +8,7 @@
  *   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.
+ *   `formatSqlDateTime`'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.
@@ -16,11 +16,11 @@
  * @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") // ""
+ * @example parseSqlDateTime("2024-03-15 14:30:00") // "2024-03-15T14:30:00"
+ * @example parseSqlDateTime("2024-03-15 14:30:00.5") // "2024-03-15T14:30:00.5"
+ * @example parseSqlDateTime("2024-03-15 14:30") // "" (seconds are required)
+ * @example parseSqlDateTime("0000-01-01 00:00:00") // "" (year outside 0001–9999)
+ * @example parseSqlDateTime("2024-03-15T14:30:00") // "" (wrong separator)
+ * @example parseSqlDateTime("not a date") // ""
  */
-export declare function parseSql(value: string): string;
+export declare function parseSqlDateTime(value: string): string;

package/dist/plain/parse/{parseSql.js → parseSqlDateTime.js}

@@ -10,7 +10,7 @@ import { sqlDateTime } from "../../regex/index.js";
  *   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.
+ *   `formatSqlDateTime`'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.
@@ -18,14 +18,14 @@ import { sqlDateTime } from "../../regex/index.js";
  * @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") // ""
+ * @example parseSqlDateTime("2024-03-15 14:30:00") // "2024-03-15T14:30:00"
+ * @example parseSqlDateTime("2024-03-15 14:30:00.5") // "2024-03-15T14:30:00.5"
+ * @example parseSqlDateTime("2024-03-15 14:30") // "" (seconds are required)
+ * @example parseSqlDateTime("0000-01-01 00:00:00") // "" (year outside 0001–9999)
+ * @example parseSqlDateTime("2024-03-15T14:30:00") // "" (wrong separator)
+ * @example parseSqlDateTime("not a date") // ""
  */
-export function parseSql(value) {
+export function parseSqlDateTime(value) {
     if (typeof value !== "string")
         return "";
     if (!sqlDateTime.test(value))