ts-time-utils 1.1.0 → 3.0.0

package/dist/iterate.js

@@ -0,0 +1,409 @@
+/**
+ * @fileoverview Date iteration utilities for generating date sequences
+ */
+/**
+ * Generate an array of dates for each day in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Array of dates, one per day
+ * @example
+ * eachDay(new Date('2024-01-01'), new Date('2024-01-05'))
+ * // [Jan 1, Jan 2, Jan 3, Jan 4, Jan 5]
+ */
+export function eachDay(start, end) {
+    const result = [];
+    const current = new Date(start.getFullYear(), start.getMonth(), start.getDate());
+    const endDate = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+    while (current <= endDate) {
+        result.push(new Date(current));
+        current.setDate(current.getDate() + 1);
+    }
+    return result;
+}
+/**
+ * Generate an array of dates for each weekday (Mon-Fri) in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Array of weekday dates
+ * @example
+ * eachWeekday(new Date('2024-01-01'), new Date('2024-01-07'))
+ * // [Jan 1 (Mon), Jan 2 (Tue), Jan 3 (Wed), Jan 4 (Thu), Jan 5 (Fri)]
+ */
+export function eachWeekday(start, end) {
+    const result = [];
+    const current = new Date(start.getFullYear(), start.getMonth(), start.getDate());
+    const endDate = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+    while (current <= endDate) {
+        const day = current.getDay();
+        if (day !== 0 && day !== 6) {
+            result.push(new Date(current));
+        }
+        current.setDate(current.getDate() + 1);
+    }
+    return result;
+}
+/**
+ * Generate an array of dates for each weekend day (Sat-Sun) in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Array of weekend dates
+ */
+export function eachWeekend(start, end) {
+    const result = [];
+    const current = new Date(start.getFullYear(), start.getMonth(), start.getDate());
+    const endDate = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+    while (current <= endDate) {
+        const day = current.getDay();
+        if (day === 0 || day === 6) {
+            result.push(new Date(current));
+        }
+        current.setDate(current.getDate() + 1);
+    }
+    return result;
+}
+/**
+ * Generate an array of dates for each week start in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @param weekStartsOn - Day week starts on (0=Sunday, 1=Monday, default: 0)
+ * @returns Array of week start dates
+ * @example
+ * eachWeek(new Date('2024-01-01'), new Date('2024-01-31'))
+ * // [Jan 7, Jan 14, Jan 21, Jan 28] (Sundays)
+ */
+export function eachWeek(start, end, weekStartsOn = 0) {
+    const result = [];
+    const current = new Date(start.getFullYear(), start.getMonth(), start.getDate());
+    const endDate = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+    // Move to first week start on or after start date
+    const dayDiff = (current.getDay() - weekStartsOn + 7) % 7;
+    if (dayDiff > 0) {
+        current.setDate(current.getDate() + (7 - dayDiff));
+    }
+    while (current <= endDate) {
+        result.push(new Date(current));
+        current.setDate(current.getDate() + 7);
+    }
+    return result;
+}
+/**
+ * Generate an array of dates for the first day of each month in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Array of first-of-month dates
+ * @example
+ * eachMonth(new Date('2024-01-15'), new Date('2024-04-15'))
+ * // [Feb 1, Mar 1, Apr 1]
+ */
+export function eachMonth(start, end) {
+    const result = [];
+    const current = new Date(start.getFullYear(), start.getMonth() + 1, 1);
+    const endDate = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+    while (current <= endDate) {
+        result.push(new Date(current));
+        current.setMonth(current.getMonth() + 1);
+    }
+    return result;
+}
+/**
+ * Generate an array of dates for the first day of each quarter in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Array of quarter start dates
+ */
+export function eachQuarter(start, end) {
+    const result = [];
+    // Start from beginning of next quarter after start date
+    const startMonth = start.getMonth();
+    const nextQuarterMonth = Math.ceil((startMonth + 1) / 3) * 3;
+    const current = new Date(nextQuarterMonth > 11 ? start.getFullYear() + 1 : start.getFullYear(), nextQuarterMonth % 12, 1);
+    const endDate = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+    while (current <= endDate) {
+        result.push(new Date(current));
+        current.setMonth(current.getMonth() + 3);
+    }
+    return result;
+}
+/**
+ * Generate an array of dates for January 1st of each year in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Array of year start dates
+ */
+export function eachYear(start, end) {
+    const result = [];
+    const startYear = start.getMonth() === 0 && start.getDate() === 1
+        ? start.getFullYear()
+        : start.getFullYear() + 1;
+    const endYear = end.getFullYear();
+    for (let year = startYear; year <= endYear; year++) {
+        result.push(new Date(year, 0, 1));
+    }
+    return result;
+}
+/**
+ * Generate an array of dates at regular hour intervals
+ * @param start - Start date/time (inclusive)
+ * @param end - End date/time (inclusive)
+ * @param step - Hour interval (default: 1)
+ * @returns Array of dates at each interval
+ * @example
+ * eachHour(new Date('2024-01-01T09:00'), new Date('2024-01-01T12:00'))
+ * // [9:00, 10:00, 11:00, 12:00]
+ */
+export function eachHour(start, end, step = 1) {
+    const result = [];
+    const current = new Date(start);
+    current.setMinutes(0, 0, 0);
+    while (current <= end) {
+        result.push(new Date(current));
+        current.setHours(current.getHours() + step);
+    }
+    return result;
+}
+/**
+ * Generate an array of dates at regular minute intervals
+ * @param start - Start date/time (inclusive)
+ * @param end - End date/time (inclusive)
+ * @param step - Minute interval (default: 1)
+ * @returns Array of dates at each interval
+ * @example
+ * eachMinute(new Date('2024-01-01T09:00'), new Date('2024-01-01T09:05'))
+ * // [9:00, 9:01, 9:02, 9:03, 9:04, 9:05]
+ */
+export function eachMinute(start, end, step = 1) {
+    const result = [];
+    const current = new Date(start);
+    current.setSeconds(0, 0);
+    while (current <= end) {
+        result.push(new Date(current));
+        current.setMinutes(current.getMinutes() + step);
+    }
+    return result;
+}
+/**
+ * Generate an array of dates for a specific day of the week in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @param dayOfWeek - Day of week (0=Sunday, 1=Monday, ..., 6=Saturday)
+ * @returns Array of dates for that day of week
+ * @example
+ * eachDayOfWeek(new Date('2024-01-01'), new Date('2024-01-31'), 1)
+ * // All Mondays in January 2024
+ */
+export function eachDayOfWeek(start, end, dayOfWeek) {
+    const result = [];
+    const current = new Date(start.getFullYear(), start.getMonth(), start.getDate());
+    const endDate = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+    // Move to first occurrence of dayOfWeek
+    const diff = (dayOfWeek - current.getDay() + 7) % 7;
+    current.setDate(current.getDate() + diff);
+    while (current <= endDate) {
+        result.push(new Date(current));
+        current.setDate(current.getDate() + 7);
+    }
+    return result;
+}
+/**
+ * Generate dates at a custom interval
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @param interval - Interval configuration
+ * @returns Array of dates at each interval
+ * @example
+ * eachInterval(start, end, { days: 3 }) // Every 3 days
+ * eachInterval(start, end, { weeks: 2 }) // Every 2 weeks
+ * eachInterval(start, end, { hours: 6 }) // Every 6 hours
+ */
+export function eachInterval(start, end, interval) {
+    const result = [];
+    const current = new Date(start);
+    while (current <= end) {
+        result.push(new Date(current));
+        if (interval.years) {
+            current.setFullYear(current.getFullYear() + interval.years);
+        }
+        if (interval.months) {
+            current.setMonth(current.getMonth() + interval.months);
+        }
+        if (interval.weeks) {
+            current.setDate(current.getDate() + interval.weeks * 7);
+        }
+        if (interval.days) {
+            current.setDate(current.getDate() + interval.days);
+        }
+        if (interval.hours) {
+            current.setHours(current.getHours() + interval.hours);
+        }
+        if (interval.minutes) {
+            current.setMinutes(current.getMinutes() + interval.minutes);
+        }
+        if (interval.seconds) {
+            current.setSeconds(current.getSeconds() + interval.seconds);
+        }
+    }
+    return result;
+}
+/**
+ * Count the number of days in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Number of days
+ */
+export function countDays(start, end) {
+    const startDay = new Date(start.getFullYear(), start.getMonth(), start.getDate());
+    const endDay = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+    return Math.round((endDay.getTime() - startDay.getTime()) / 86400000) + 1;
+}
+/**
+ * Count the number of weekdays in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Number of weekdays
+ */
+export function countWeekdays(start, end) {
+    return eachWeekday(start, end).length;
+}
+/**
+ * Count the number of weekend days in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Number of weekend days
+ */
+export function countWeekendDays(start, end) {
+    return eachWeekend(start, end).length;
+}
+/**
+ * Count the number of weeks (complete or partial) in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Number of weeks
+ */
+export function countWeeks(start, end) {
+    const days = countDays(start, end);
+    return Math.ceil(days / 7);
+}
+/**
+ * Count the number of months in a range
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @returns Number of months (partial months count as 1)
+ */
+export function countMonths(start, end) {
+    const yearDiff = end.getFullYear() - start.getFullYear();
+    const monthDiff = end.getMonth() - start.getMonth();
+    return yearDiff * 12 + monthDiff + 1;
+}
+/**
+ * Iterator for lazy date generation (memory efficient for large ranges)
+ * @param start - Start date (inclusive)
+ * @param end - End date (inclusive)
+ * @param step - Step function to advance the date
+ * @yields Date objects
+ */
+export function* iterateDates(start, end, step = (d) => d.setDate(d.getDate() + 1)) {
+    const current = new Date(start);
+    while (current <= end) {
+        yield new Date(current);
+        step(current);
+    }
+}
+/**
+ * Create a lazy day iterator
+ * @param start - Start date
+ * @param end - End date
+ * @yields Each day in the range
+ */
+export function* iterateDays(start, end) {
+    yield* iterateDates(start, end, (d) => d.setDate(d.getDate() + 1));
+}
+/**
+ * Create a lazy weekday iterator
+ * @param start - Start date
+ * @param end - End date
+ * @yields Each weekday in the range
+ */
+export function* iterateWeekdays(start, end) {
+    const current = new Date(start.getFullYear(), start.getMonth(), start.getDate());
+    while (current <= end) {
+        const day = current.getDay();
+        if (day !== 0 && day !== 6) {
+            yield new Date(current);
+        }
+        current.setDate(current.getDate() + 1);
+    }
+}
+/**
+ * Create a lazy month iterator
+ * @param start - Start date
+ * @param end - End date
+ * @yields First day of each month in the range
+ */
+export function* iterateMonths(start, end) {
+    const current = new Date(start.getFullYear(), start.getMonth(), 1);
+    while (current <= end) {
+        yield new Date(current);
+        current.setMonth(current.getMonth() + 1);
+    }
+}
+/**
+ * Generate dates by applying a filter to a range
+ * @param start - Start date
+ * @param end - End date
+ * @param filter - Filter function (return true to include date)
+ * @returns Array of filtered dates
+ * @example
+ * // Get all 15th days of each month
+ * filterDays(start, end, d => d.getDate() === 15)
+ */
+export function filterDays(start, end, filter) {
+    const result = [];
+    for (const date of iterateDays(start, end)) {
+        if (filter(date)) {
+            result.push(date);
+        }
+    }
+    return result;
+}
+/**
+ * Generate the last day of each month in a range
+ * @param start - Start date
+ * @param end - End date
+ * @returns Array of last-of-month dates
+ */
+export function eachMonthEnd(start, end) {
+    const result = [];
+    const current = new Date(start.getFullYear(), start.getMonth() + 1, 0);
+    const endDate = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+    while (current <= endDate) {
+        result.push(new Date(current));
+        current.setMonth(current.getMonth() + 2);
+        current.setDate(0); // Last day of previous month
+    }
+    return result;
+}
+/**
+ * Generate specific day of each month in a range
+ * @param start - Start date
+ * @param end - End date
+ * @param dayOfMonth - Day of month (1-31, will cap at month's max)
+ * @returns Array of dates
+ * @example
+ * eachNthDayOfMonth(start, end, 15) // 15th of each month
+ * eachNthDayOfMonth(start, end, 31) // Last day of short months, 31st otherwise
+ */
+export function eachNthDayOfMonth(start, end, dayOfMonth) {
+    const result = [];
+    let current = new Date(start.getFullYear(), start.getMonth(), 1);
+    const endDate = new Date(end.getFullYear(), end.getMonth(), end.getDate());
+    while (current <= endDate) {
+        const daysInMonth = new Date(current.getFullYear(), current.getMonth() + 1, 0).getDate();
+        const actualDay = Math.min(dayOfMonth, daysInMonth);
+        const date = new Date(current.getFullYear(), current.getMonth(), actualDay);
+        if (date >= start && date <= endDate) {
+            result.push(date);
+        }
+        current.setMonth(current.getMonth() + 1);
+    }
+    return result;
+}

package/dist/parse.d.ts

@@ -28,4 +28,49 @@ export declare function parseCustomFormat(dateString: string, format: string): D
  * @param formats - array of format patterns to try
  */
 export declare function parseManyFormats(dateString: string, formats: string[]): Date | null;
+/**
+ * Parse an ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S")
+ * @param duration - ISO 8601 duration string
+ * @returns object with parsed components
+ */
+export declare function parseISO8601Duration(duration: string): {
+    years: number;
+    months: number;
+    weeks: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+} | null;
+/**
+ * Convert ISO 8601 duration to milliseconds (approximate for months/years)
+ * @param duration - ISO 8601 duration string
+ */
+export declare function parseISO8601DurationToMs(duration: string): number | null;
+/**
+ * Parse a time string (e.g., "14:30", "2:30 PM", "14:30:45")
+ * @param timeString - time string to parse
+ * @returns object with hours, minutes, seconds, or null if invalid
+ */
+export declare function parseTime(timeString: string): {
+    hours: number;
+    minutes: number;
+    seconds: number;
+} | null;
+/**
+ * Guess the date format of a date string
+ * @param dateString - date string to analyze
+ * @returns detected format pattern or null
+ */
+export declare function guessDateFormat(dateString: string): string | null;
+/**
+ * Parse a date string using auto-detected format
+ * @param dateString - date string to parse
+ */
+export declare function parseAutoFormat(dateString: string): Date | null;
+/**
+ * Parse a date from a natural language date range endpoint
+ * @param input - string like "end of month", "start of year", "beginning of week"
+ */
+export declare function parseRangeEndpoint(input: string): Date | null;
 //# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CA6C5D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAiBvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAmDjF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAMnF"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CA6C5D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAiBvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAmDjF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAMnF;AAqCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CA4CP;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqBxE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CAuCP;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoCjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAmB/D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CA2C7D"}

package/dist/parse.js

@@ -215,3 +215,210 @@ function addTimeUnits(date, amount, unit) {
 function subtractTimeUnits(date, amount, unit) {
     return addTimeUnits(date, -amount, unit);
 }
+/**
+ * Parse an ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S")
+ * @param duration - ISO 8601 duration string
+ * @returns object with parsed components
+ */
+export function parseISO8601Duration(duration) {
+    // ISO 8601 duration format: P[n]Y[n]M[n]DT[n]H[n]M[n]S or P[n]W
+    const result = {
+        years: 0,
+        months: 0,
+        weeks: 0,
+        days: 0,
+        hours: 0,
+        minutes: 0,
+        seconds: 0,
+    };
+    const normalized = duration.toUpperCase().trim();
+    if (!normalized.startsWith('P')) {
+        return null;
+    }
+    // Handle week format: P[n]W
+    const weekMatch = normalized.match(/^P(\d+)W$/);
+    if (weekMatch) {
+        result.weeks = parseInt(weekMatch[1]);
+        return result;
+    }
+    // Full format: P[n]Y[n]M[n]DT[n]H[n]M[n]S
+    const fullMatch = normalized.match(/^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/);
+    if (!fullMatch) {
+        return null;
+    }
+    const [, years, months, days, hours, minutes, seconds] = fullMatch;
+    if (years)
+        result.years = parseInt(years);
+    if (months)
+        result.months = parseInt(months);
+    if (days)
+        result.days = parseInt(days);
+    if (hours)
+        result.hours = parseInt(hours);
+    if (minutes)
+        result.minutes = parseInt(minutes);
+    if (seconds)
+        result.seconds = parseFloat(seconds);
+    return result;
+}
+/**
+ * Convert ISO 8601 duration to milliseconds (approximate for months/years)
+ * @param duration - ISO 8601 duration string
+ */
+export function parseISO8601DurationToMs(duration) {
+    const parsed = parseISO8601Duration(duration);
+    if (!parsed)
+        return null;
+    const MS_PER_SECOND = 1000;
+    const MS_PER_MINUTE = 60 * MS_PER_SECOND;
+    const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+    const MS_PER_DAY = 24 * MS_PER_HOUR;
+    const MS_PER_WEEK = 7 * MS_PER_DAY;
+    const MS_PER_MONTH = 30 * MS_PER_DAY; // Approximate
+    const MS_PER_YEAR = 365 * MS_PER_DAY; // Approximate
+    return (parsed.years * MS_PER_YEAR +
+        parsed.months * MS_PER_MONTH +
+        parsed.weeks * MS_PER_WEEK +
+        parsed.days * MS_PER_DAY +
+        parsed.hours * MS_PER_HOUR +
+        parsed.minutes * MS_PER_MINUTE +
+        parsed.seconds * MS_PER_SECOND);
+}
+/**
+ * Parse a time string (e.g., "14:30", "2:30 PM", "14:30:45")
+ * @param timeString - time string to parse
+ * @returns object with hours, minutes, seconds, or null if invalid
+ */
+export function parseTime(timeString) {
+    const normalized = timeString.trim();
+    // 24-hour format: HH:MM or HH:MM:SS
+    const match24 = normalized.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/);
+    if (match24) {
+        const hours = parseInt(match24[1]);
+        const minutes = parseInt(match24[2]);
+        const seconds = match24[3] ? parseInt(match24[3]) : 0;
+        if (hours >= 0 && hours <= 23 && minutes >= 0 && minutes <= 59 && seconds >= 0 && seconds <= 59) {
+            return { hours, minutes, seconds };
+        }
+        return null;
+    }
+    // 12-hour format: H:MM AM/PM or HH:MM AM/PM
+    const match12 = normalized.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?\s*(AM|PM|am|pm)$/i);
+    if (match12) {
+        let hours = parseInt(match12[1]);
+        const minutes = parseInt(match12[2]);
+        const seconds = match12[3] ? parseInt(match12[3]) : 0;
+        const isPM = match12[4].toLowerCase() === 'pm';
+        if (hours < 1 || hours > 12 || minutes < 0 || minutes > 59 || seconds < 0 || seconds > 59) {
+            return null;
+        }
+        // Convert to 24-hour format
+        if (isPM && hours !== 12) {
+            hours += 12;
+        }
+        else if (!isPM && hours === 12) {
+            hours = 0;
+        }
+        return { hours, minutes, seconds };
+    }
+    return null;
+}
+/**
+ * Guess the date format of a date string
+ * @param dateString - date string to analyze
+ * @returns detected format pattern or null
+ */
+export function guessDateFormat(dateString) {
+    const normalized = dateString.trim();
+    // YYYY-MM-DD
+    if (/^\d{4}-\d{2}-\d{2}$/.test(normalized)) {
+        return 'YYYY-MM-DD';
+    }
+    // DD/MM/YYYY or MM/DD/YYYY - need to analyze values
+    if (/^\d{2}\/\d{2}\/\d{4}$/.test(normalized)) {
+        const [first, second] = normalized.split('/').map(Number);
+        if (first > 12)
+            return 'DD/MM/YYYY'; // First must be day
+        if (second > 12)
+            return 'MM/DD/YYYY'; // Second must be day
+        // Ambiguous - default to US format
+        return 'MM/DD/YYYY';
+    }
+    // DD-MM-YYYY or MM-DD-YYYY
+    if (/^\d{2}-\d{2}-\d{4}$/.test(normalized)) {
+        const [first, second] = normalized.split('-').map(Number);
+        if (first > 12)
+            return 'DD-MM-YYYY';
+        if (second > 12)
+            return 'MM-DD-YYYY';
+        return 'MM-DD-YYYY';
+    }
+    // YYYYMMDD
+    if (/^\d{8}$/.test(normalized)) {
+        return 'YYYYMMDD';
+    }
+    // ISO 8601 with time
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(normalized)) {
+        return 'ISO8601';
+    }
+    return null;
+}
+/**
+ * Parse a date string using auto-detected format
+ * @param dateString - date string to parse
+ */
+export function parseAutoFormat(dateString) {
+    const format = guessDateFormat(dateString);
+    if (!format) {
+        return parseDate(dateString);
+    }
+    if (format === 'ISO8601') {
+        return parseDate(dateString);
+    }
+    if (format === 'YYYYMMDD') {
+        const year = parseInt(dateString.slice(0, 4));
+        const month = parseInt(dateString.slice(4, 6)) - 1;
+        const day = parseInt(dateString.slice(6, 8));
+        return new Date(year, month, day);
+    }
+    return parseCustomFormat(dateString, format);
+}
+/**
+ * Parse a date from a natural language date range endpoint
+ * @param input - string like "end of month", "start of year", "beginning of week"
+ */
+export function parseRangeEndpoint(input) {
+    const now = new Date();
+    const lowercaseInput = input.toLowerCase().trim();
+    // Start/beginning of period
+    if (lowercaseInput.match(/^(start|beginning)\s+of\s+(this\s+)?(day|today)$/)) {
+        return new Date(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0, 0);
+    }
+    if (lowercaseInput.match(/^(start|beginning)\s+of\s+(this\s+)?week$/)) {
+        const day = now.getDay();
+        const diff = now.getDate() - day + (day === 0 ? -6 : 1); // Monday
+        return new Date(now.getFullYear(), now.getMonth(), diff, 0, 0, 0, 0);
+    }
+    if (lowercaseInput.match(/^(start|beginning)\s+of\s+(this\s+)?month$/)) {
+        return new Date(now.getFullYear(), now.getMonth(), 1, 0, 0, 0, 0);
+    }
+    if (lowercaseInput.match(/^(start|beginning)\s+of\s+(this\s+)?year$/)) {
+        return new Date(now.getFullYear(), 0, 1, 0, 0, 0, 0);
+    }
+    // End of period
+    if (lowercaseInput.match(/^end\s+of\s+(this\s+)?(day|today)$/)) {
+        return new Date(now.getFullYear(), now.getMonth(), now.getDate(), 23, 59, 59, 999);
+    }
+    if (lowercaseInput.match(/^end\s+of\s+(this\s+)?week$/)) {
+        const day = now.getDay();
+        const diff = now.getDate() - day + (day === 0 ? 0 : 7); // Sunday
+        return new Date(now.getFullYear(), now.getMonth(), diff, 23, 59, 59, 999);
+    }
+    if (lowercaseInput.match(/^end\s+of\s+(this\s+)?month$/)) {
+        return new Date(now.getFullYear(), now.getMonth() + 1, 0, 23, 59, 59, 999);
+    }
+    if (lowercaseInput.match(/^end\s+of\s+(this\s+)?year$/)) {
+        return new Date(now.getFullYear(), 11, 31, 23, 59, 59, 999);
+    }
+    return null;
+}