feat: add defaultDate option to parse/isValid for partial date string support

Introduce ParsedComponents interface in parser.ts and refactor PreparseResult
to extend it. Add defaultDate option to ParserOptions so callers can supply
fallback values for components missing from the format string.

- toGregorianYear/getDefaultDate helpers extracted in isValid.ts for reuse
- validatePreparseResult now validates defaultDate components (e.g. H, Z)
- parse() merges parsed values with defaultDate, respecting precedence rules:
  defaultDate.Z takes precedence over options.timeZone

Author: knowledgecode

src/isValid.ts

@@ -1,35 +1,67 @@
 import { preparse } from './preparse.ts';
 import { getDaysInMonth } from './utils.ts';
 import type { CompiledObject } from './compile.ts';
-import type { ParserOptions } from './parser.ts';
+import type { ParsedComponents, ParserOptions } from './parser.ts';
 import type { PreparseResult } from './preparse.ts';
 
+/**
+ * Converts a year to the Gregorian calendar year based on the specified calendar system in the parser options.
+ * @param year - The year to convert, which may be in a non-Gregorian calendar system (e.g., Buddhist calendar)
+ * @param [options] - Optional parser options that may specify the calendar system to use for conversion
+ * @returns The corresponding Gregorian calendar year, or undefined if the input year is undefined
+ */
+export const toGregorianYear = (year: number | undefined, options?: ParserOptions) => {
+  return year === undefined ? year : year - (options?.calendar === 'buddhist' ? 543 : 0);
+};
+
+/**
+ * Gets the default date components to use when certain components are missing from the input string.
+ * @param [defaultDate] - An object containing default date components (year, month, day, hour, minute, second, millisecond, timezone offset)
+ * @returns An object with all date components filled in, using the provided default values or fallback defaults (e.g., year defaults to 1970)
+ */
+export const getDefaultDate = (defaultDate: ParsedComponents = {}) => {
+  return {
+    Y: defaultDate.Y ?? 1970,
+    M: defaultDate.M ?? 1,
+    D: defaultDate.D ?? 1,
+    H: defaultDate.H,
+    A: defaultDate.A,
+    h: defaultDate.h,
+    m: defaultDate.m ?? 0,
+    s: defaultDate.s ?? 0,
+    S: defaultDate.S ?? 0,
+    Z: defaultDate.Z
+  };
+};
+
 /**
  * Validates whether a preparse result object is valid.
  * @param pr - The preparse result object to validate
  * @param [options] - Optional parser options
  * @returns True if the preparse result is valid, false otherwise
  */
 export function validatePreparseResult(pr: PreparseResult, options?: ParserOptions) {
-  const y = pr.Y === undefined ? 1970 : pr.Y - (options?.calendar === 'buddhist' ? 543 : 0);
   const [min12, max12] = options?.hour12 === 'h11' ? [0, 11] : [1, 12];
   const [min24, max24] = options?.hour24 === 'h24' ? [1, 24] : [0, 23];
   const range = (value: number | undefined, min: number, max: number) => value === undefined || value >= min && value <= max;
+  const base = getDefaultDate(options?.defaultDate);
+  const year = toGregorianYear(pr.Y, options) ?? base.Y;
+  const month = pr.M ?? base.M;
 
   return pr._index > 0
     && pr._length > 0
     && pr._index === pr._length
     && pr._match > 0
-    && range(y, 1, 9999)
-    && range(pr.M, 1, 12)
-    && range(pr.D, 1, getDaysInMonth(y, pr.M ?? 1))
-    && range(pr.H, min24, max24)
-    && range(pr.A, 0, 1)
-    && range(pr.h, min12, max12)
-    && range(pr.m, 0, 59)
-    && range(pr.s, 0, 59)
-    && range(pr.S, 0, 999)
-    && range(pr.Z, -913, 956);
+    && range(year, 1, 9999)
+    && range(month, 1, 12)
+    && range(pr.D ?? base.D, 1, getDaysInMonth(year, month))
+    && range(pr.H ?? base.H, min24, max24)
+    && range(pr.A ?? base.A, 0, 1)
+    && range(pr.h ?? base.h, min12, max12)
+    && range(pr.m ?? base.m, 0, 59)
+    && range(pr.s ?? base.s, 0, 59)
+    && range(pr.S ?? base.S, 0, 999)
+    && range(pr.Z ?? base.Z, -913, 956);
 }
 
 /**

src/parse.ts

@@ -1,10 +1,21 @@
-import { createTimezoneDate } from './zone.ts';
+import { createTimezoneDate, TimeZone } from './zone.ts';
 import { isUTC } from './datetime.ts';
 import { preparse } from './preparse.ts';
-import { validatePreparseResult } from './isValid.ts';
+import { toGregorianYear, getDefaultDate, validatePreparseResult } from './isValid.ts';
 import type { CompiledObject } from './compile.ts';
 import type { ParserOptions } from './parser.ts';
 
+const convert = (Y: number, M: number, D: number, H: number, m: number, s: number, S: number, timeZone?: string | TimeZone) => {
+  // If a specific time zone is provided in the options, use it to create the date.
+  if (timeZone) {
+    const naiveUTC = Date.UTC(Y, M - 1, D, H, m, s, S);
+    // If the specified time zone is UTC, create the date directly in UTC. Otherwise, create the date using the specified time zone.
+    return isUTC(timeZone) ? new Date(naiveUTC) : createTimezoneDate(naiveUTC, timeZone);
+  }
+  // If no time zone is provided, create the date in the local time zone.
+  return new Date(Y, M - 1, D, H, m, s, S);
+};
+
 /**
  * Parses a date string according to the specified format.
  * @param dateString - The date string to parse
@@ -18,23 +29,20 @@ export function parse(dateString: string, arg: string | CompiledObject, options?
   if (!validatePreparseResult(pr, options)) {
     return new Date(NaN);
   }
-  // Normalize date components (year, month, day, hour, minute, second, millisecond)
-  pr.Y = pr.Y ? pr.Y - (options?.calendar === 'buddhist' ? 543 : 0) : 1970;
-  pr.M = (pr.M ?? 1) - (pr.Y < 100 ? 1900 * 12 + 1 : 1);
-  pr.D ??= 1;
-  pr.H = ((pr.H ?? 0) % 24) || ((pr.A ?? 0) * 12 + (pr.h ?? 0) % 12);
-  pr.m ??= 0;
-  pr.s ??= 0;
-  pr.S ??= 0;
 
-  // If the preparse result contains a timezone offset (Z), use it to create the date.
-  if (isUTC(options?.timeZone) || 'Z' in pr) {
-    return new Date(Date.UTC(pr.Y, pr.M, pr.D, pr.H, pr.m + (pr.Z ?? 0), pr.s, pr.S));
-  }
-  // If a specific time zone is provided in the options, use it to create the date.
-  if (options?.timeZone) {
-    return createTimezoneDate(Date.UTC(pr.Y, pr.M, pr.D, pr.H, pr.m, pr.s, pr.S), options.timeZone);
-  }
-  // If no time zone information is available, create the date in the local time zone.
-  return new Date(pr.Y, pr.M, pr.D, pr.H, pr.m, pr.s, pr.S);
+  const base = getDefaultDate(options?.defaultDate);
+  const year = toGregorianYear(pr.Y, options) ?? base.Y;
+  // When a Z offset exists (from the parsed string or defaultDate.Z), it takes precedence over options.timeZone.
+  const offset = pr.Z ?? base.Z;
+
+  return convert(
+    year,
+    (pr.M ?? base.M) - (year < 100 ? 1900 * 12 : 0),
+    pr.D ?? base.D,
+    ((pr.H ?? base.H ?? 0) % 24) || ((pr.A ?? base.A ?? 0) * 12 + (pr.h ?? base.h ?? 0) % 12),
+    (pr.m ?? base.m) + (offset ?? 0),
+    pr.s ?? base.s,
+    pr.S ?? base.S,
+    typeof offset === 'number' ? 'UTC' : options?.timeZone
+  );
 }

src/parser.ts

@@ -5,6 +5,58 @@ import type { TimeZone } from './zone.ts';
 
 type ParserToken = 'Y' | 'M' | 'D' | 'H' | 'A' | 'h' | 'm' | 's' | 'S' | 'Z';
 
+export interface ParsedComponents {
+  /**
+   * Year component
+   */
+  Y?: number;
+
+  /**
+   * Month component (1-12)
+   */
+  M?: number;
+
+  /**
+   * Day component
+   */
+  D?: number;
+
+  /**
+   * Hour in 24-hour format
+   */
+  H?: number;
+
+  /**
+   * Meridiem indicator (0:AM / 1:PM)
+   */
+  A?: number;
+
+  /**
+   * Hour in 12-hour format
+   */
+  h?: number;
+
+  /**
+   * Minute component
+   */
+  m?: number;
+
+  /**
+   * Second component
+   */
+  s?: number;
+
+  /**
+   * Millisecond component
+   */
+  S?: number;
+
+  /**
+   * Timezone offset in minutes
+   */
+  Z?: number;
+}
+
 export interface ParserPluginOptions {
   /**
    * The hour format to use for parsing.
@@ -51,6 +103,13 @@ export interface ParserPluginOptions {
    * This is an object that provides methods to get localized month names, day names, and meridiems.
    */
   locale: Locale;
+
+  /**
+   * Default date components to use when certain components are missing from the input string.
+   * This allows the parser to fill in missing components with default values, which can be useful for parsing partial date strings.
+   * For example, if the input string only contains a month and day, the parser can use the default year from this object.
+   */
+  defaultDate: ParsedComponents;
 }
 
 export interface ParseResult {

src/preparse.ts

@@ -4,59 +4,9 @@ import { parser as defaultParser, validateToken } from './parser.ts';
 import en from './locales/en.ts';
 import latn from './numerals/latn.ts';
 import type { CompiledObject } from './compile.ts';
-import type { ParserOptions } from './parser.ts';
-
-export interface PreparseResult {
-  /**
-   * Year component
-   */
-  Y?: number;
-
-  /**
-   * Month component (1-12)
-   */
-  M?: number;
-
-  /**
-   * Day component
-   */
-  D?: number;
-
-  /**
-   * Hour in 24-hour format
-   */
-  H?: number;
-
-  /**
-   * Meridiem indicator (0:AM/1:PM)
-   */
-  A?: number;
-
-  /**
-   * Hour in 12-hour format
-   */
-  h?: number;
-
-  /**
-   * Minute component
-   */
-  m?: number;
-
-  /**
-   * Second component
-   */
-  s?: number;
-
-  /**
-   * Millisecond component
-   */
-  S?: number;
-
-  /**
-   * Timezone offset in minutes
-   */
-  Z?: number;
+import type { ParsedComponents, ParserOptions } from './parser.ts';
 
+export interface PreparseResult extends ParsedComponents {
   /**
    * Current parsing position
    */
@@ -95,7 +45,8 @@ export function preparse(dateString: string, arg: string | CompiledObject, optio
     timeZone: isTimeZone(options?.timeZone) || typeof options?.timeZone === 'string'
       ? options.timeZone || undefined
       : undefined,
-    locale: options?.locale ?? en
+    locale: options?.locale ?? en,
+    defaultDate: options?.defaultDate ?? {}
   };
   const pr: PreparseResult = {
     _index: 0,