ts-time-utils 1.0.0 → 2.0.0

package/dist/naturalLanguage.js

@@ -0,0 +1,344 @@
+/**
+ * @fileoverview Natural language date parsing utilities
+ * Provides intelligent parsing of human-readable date strings
+ */
+import { addTime } from './calculate.js';
+import { parseRelativeDate } from './parse.js';
+/**
+ * Parses natural language date strings into Date objects
+ * @param input - Natural language date string
+ * @param options - Parsing options
+ * @returns Parsed date or null if unable to parse
+ *
+ * @example
+ * ```ts
+ * parseNaturalDate('tomorrow at 3pm');
+ * // Date for tomorrow at 15:00
+ *
+ * parseNaturalDate('next Friday');
+ * // Date for next Friday
+ *
+ * parseNaturalDate('in 2 weeks');
+ * // Date 2 weeks from now
+ *
+ * parseNaturalDate('December 25th');
+ * // Date for Dec 25 this year (or next if passed)
+ * ```
+ */
+export function parseNaturalDate(input, options = {}) {
+    const { referenceDate = new Date(), defaultTime } = options;
+    const normalized = input.toLowerCase().trim();
+    // Try relative phrase parser first (handles "next week", "last month", etc.)
+    const relativePhraseResult = parseRelativePhrase(input, referenceDate);
+    if (relativePhraseResult)
+        return relativePhraseResult;
+    // Try existing relative date parser
+    const relativeResult = parseRelativeDate(input);
+    if (relativeResult)
+        return relativeResult;
+    // Common absolute patterns
+    const absolutePatterns = [
+        // "next Friday", "last Monday"
+        /^(next|last|this)\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)$/,
+        // "Friday", "Monday" (interpreted as next occurrence)
+        /^(monday|tuesday|wednesday|thursday|friday|saturday|sunday)$/,
+        // "tomorrow at 3pm", "today at noon"
+        /^(today|tomorrow|yesterday)\s+at\s+(.+)$/,
+        // "3pm today", "noon tomorrow"
+        /^(.+?)\s+(today|tomorrow|yesterday)$/,
+        // "in 2 weeks", "in 3 days"
+        /^in\s+(\d+)\s+(minute|minutes|hour|hours|day|days|week|weeks|month|months|year|years)$/,
+        // "2 weeks from now", "3 days ago"
+        /^(\d+)\s+(minute|minutes|hour|hours|day|days|week|weeks|month|months|year|years)\s+(from now|ago)$/,
+        // "December 25", "Dec 25", "25 December"
+        /^(january|february|march|april|may|june|july|august|september|october|november|december|jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\s+(\d{1,2})(st|nd|rd|th)?$/,
+        /^(\d{1,2})(st|nd|rd|th)?\s+(january|february|march|april|may|june|july|august|september|october|november|december|jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)$/,
+    ];
+    // Check each pattern
+    for (const pattern of absolutePatterns) {
+        const match = normalized.match(pattern);
+        if (match) {
+            return parseMatchedPattern(match, referenceDate, defaultTime);
+        }
+    }
+    // Try standard Date parsing as fallback
+    const standardDate = new Date(input);
+    if (!isNaN(standardDate.getTime())) {
+        return standardDate;
+    }
+    return null;
+}
+/**
+ * Parses a relative time phrase into a Date
+ * @param input - Relative time phrase
+ * @param referenceDate - Reference date (defaults to now)
+ * @returns Parsed date or null
+ *
+ * @example
+ * ```ts
+ * parseRelativePhrase('in 2 hours'); // 2 hours from now
+ * parseRelativePhrase('5 minutes ago'); // 5 minutes ago
+ * parseRelativePhrase('next week'); // 7 days from now
+ * ```
+ */
+export function parseRelativePhrase(input, referenceDate = new Date()) {
+    const normalized = input.toLowerCase().trim();
+    // "in X units"
+    const inPattern = /^in\s+(\d+)\s+(millisecond|milliseconds|second|seconds|minute|minutes|hour|hours|day|days|week|weeks|month|months|year|years)$/;
+    let match = normalized.match(inPattern);
+    if (match) {
+        const amount = parseInt(match[1], 10);
+        const unit = normalizeUnit(match[2]);
+        return addTime(referenceDate, amount, unit);
+    }
+    // "X units ago"
+    const agoPattern = /^(\d+)\s+(millisecond|milliseconds|second|seconds|minute|minutes|hour|hours|day|days|week|weeks|month|months|year|years)\s+ago$/;
+    match = normalized.match(agoPattern);
+    if (match) {
+        const amount = parseInt(match[1], 10);
+        const unit = normalizeUnit(match[2]);
+        return addTime(referenceDate, -amount, unit);
+    }
+    // "X units from now"
+    const fromNowPattern = /^(\d+)\s+(millisecond|milliseconds|second|seconds|minute|minutes|hour|hours|day|days|week|weeks|month|months|year|years)\s+from\s+now$/;
+    match = normalized.match(fromNowPattern);
+    if (match) {
+        const amount = parseInt(match[1], 10);
+        const unit = normalizeUnit(match[2]);
+        return addTime(referenceDate, amount, unit);
+    }
+    // Common shortcuts - use switch/case to properly use the referenceDate parameter
+    switch (normalized) {
+        case 'now':
+            return new Date(referenceDate);
+        case 'today': {
+            const d = new Date(referenceDate);
+            d.setHours(0, 0, 0, 0);
+            return d;
+        }
+        case 'tomorrow':
+            return addTime(referenceDate, 1, 'day');
+        case 'yesterday':
+            return addTime(referenceDate, -1, 'day');
+        case 'next week':
+            return addTime(referenceDate, 1, 'week');
+        case 'last week':
+            return addTime(referenceDate, -1, 'week');
+        case 'next month':
+            return addTime(referenceDate, 1, 'month');
+        case 'last month':
+            return addTime(referenceDate, -1, 'month');
+        case 'next year':
+            return addTime(referenceDate, 1, 'year');
+        case 'last year':
+            return addTime(referenceDate, -1, 'year');
+        default:
+            return null;
+    }
+}
+/**
+ * Extracts all dates from a text string
+ * @param text - Text to extract dates from
+ * @param options - Extraction options
+ * @returns Array of extracted date information
+ *
+ * @example
+ * ```ts
+ * const text = "Meeting tomorrow at 3pm and dinner next Friday at 7pm";
+ * const dates = extractDatesFromText(text);
+ * // [
+ * //   { date: Date(...), text: 'tomorrow at 3pm', index: 8, ... },
+ * //   { date: Date(...), text: 'next Friday at 7pm', index: 37, ... }
+ * // ]
+ * ```
+ */
+export function extractDatesFromText(text, options = {}) {
+    const { referenceDate = new Date() } = options;
+    const results = [];
+    // Patterns to match
+    const patterns = [
+        // Relative dates
+        /\b(tomorrow|yesterday|today)\b/gi,
+        /\b(next|last|this)\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday|week|month|year)\b/gi,
+        /\bin\s+\d+\s+(minute|minutes|hour|hours|day|days|week|weeks|month|months|year|years)\b/gi,
+        /\b\d+\s+(minute|minutes|hour|hours|day|days|week|weeks|month|months|year|years)\s+(ago|from now)\b/gi,
+        // Absolute dates
+        /\b(january|february|march|april|may|june|july|august|september|october|november|december|jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\s+\d{1,2}(st|nd|rd|th)?\b/gi,
+        /\b\d{1,2}(st|nd|rd|th)?\s+(of\s+)?(january|february|march|april|may|june|july|august|september|october|november|december|jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\b/gi,
+        // Date formats
+        /\b\d{1,2}[\/\-\.]\d{1,2}[\/\-\.]\d{2,4}\b/g,
+        /\b\d{4}[\/\-\.]\d{1,2}[\/\-\.]\d{1,2}\b/g,
+        // Time patterns (when found with dates)
+        /\bat\s+\d{1,2}(:\d{2})?\s*(am|pm|AM|PM)?\b/gi,
+    ];
+    const processed = new Set();
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            const matchedText = match[0];
+            const index = match.index;
+            // Skip if already processed
+            if (processed.has(`${index}-${matchedText}`))
+                continue;
+            processed.add(`${index}-${matchedText}`);
+            // Try to parse the matched text
+            const parsed = parseNaturalDate(matchedText, { referenceDate });
+            if (parsed) {
+                results.push({
+                    date: parsed,
+                    text: matchedText,
+                    index,
+                    type: determineType(matchedText),
+                    confidence: calculateConfidence(matchedText)
+                });
+            }
+        }
+    }
+    // Sort by index (order in text)
+    return results.sort((a, b) => a.index - b.index);
+}
+/**
+ * Suggests possible dates based on context
+ * @param context - Context string to analyze
+ * @param options - Parsing options
+ * @returns Array of suggested dates with confidence scores
+ *
+ * @example
+ * ```ts
+ * suggestDateFromContext('deadline is end of month');
+ * // [{ date: Date(last day of current month), confidence: 0.8, ... }]
+ * ```
+ */
+export function suggestDateFromContext(context, options = {}) {
+    const { referenceDate = new Date() } = options;
+    const suggestions = [];
+    const normalized = context.toLowerCase();
+    // End of month
+    if (normalized.includes('end of month') || normalized.includes('eom')) {
+        const date = new Date(referenceDate.getFullYear(), referenceDate.getMonth() + 1, 0);
+        suggestions.push({ date, text: 'end of month', confidence: 0.85 });
+    }
+    // Beginning of month
+    if (normalized.includes('beginning of month') || normalized.includes('start of month')) {
+        const date = new Date(referenceDate.getFullYear(), referenceDate.getMonth(), 1);
+        suggestions.push({ date, text: 'beginning of month', confidence: 0.85 });
+    }
+    // End of year
+    if (normalized.includes('end of year') || normalized.includes('eoy')) {
+        const date = new Date(referenceDate.getFullYear(), 11, 31);
+        suggestions.push({ date, text: 'end of year', confidence: 0.85 });
+    }
+    // Beginning of year
+    if (normalized.includes('beginning of year') || normalized.includes('start of year')) {
+        const date = new Date(referenceDate.getFullYear(), 0, 1);
+        suggestions.push({ date, text: 'beginning of year', confidence: 0.85 });
+    }
+    // End of week
+    if (normalized.includes('end of week') || normalized.includes('eow')) {
+        const date = new Date(referenceDate);
+        const day = date.getDay();
+        const diff = 6 - day; // Saturday
+        date.setDate(date.getDate() + diff);
+        suggestions.push({ date, text: 'end of week', confidence: 0.85 });
+    }
+    // Extract any explicit dates
+    const extracted = extractDatesFromText(context, options);
+    for (const item of extracted) {
+        suggestions.push({
+            date: item.date,
+            text: item.text,
+            confidence: item.confidence
+        });
+    }
+    // Sort by confidence
+    return suggestions.sort((a, b) => b.confidence - a.confidence);
+}
+// Helper functions
+function parseMatchedPattern(match, referenceDate, defaultTime) {
+    const pattern = match[0];
+    // Weekday patterns
+    if (pattern.includes('monday') || pattern.includes('tuesday') ||
+        pattern.includes('wednesday') || pattern.includes('thursday') ||
+        pattern.includes('friday') || pattern.includes('saturday') ||
+        pattern.includes('sunday')) {
+        const weekdayMap = {
+            'sunday': 0, 'monday': 1, 'tuesday': 2, 'wednesday': 3,
+            'thursday': 4, 'friday': 5, 'saturday': 6
+        };
+        const weekday = Object.keys(weekdayMap).find(day => pattern.includes(day));
+        if (!weekday)
+            return null;
+        const targetDay = weekdayMap[weekday];
+        const currentDay = referenceDate.getDay();
+        let daysToAdd = targetDay - currentDay;
+        if (pattern.includes('next')) {
+            if (daysToAdd <= 0)
+                daysToAdd += 7;
+        }
+        else if (pattern.includes('last')) {
+            if (daysToAdd >= 0)
+                daysToAdd -= 7;
+        }
+        else {
+            // "this" or just the weekday name - go to next occurrence
+            if (daysToAdd <= 0)
+                daysToAdd += 7;
+        }
+        return addTime(referenceDate, daysToAdd, 'day');
+    }
+    // "in X units" pattern
+    if (match[1] && match[2]) {
+        const amount = parseInt(match[1], 10);
+        const unit = normalizeUnit(match[2]);
+        if (match[3] === 'ago') {
+            return addTime(referenceDate, -amount, unit);
+        }
+        return addTime(referenceDate, amount, unit);
+    }
+    return null;
+}
+function normalizeUnit(unit) {
+    const normalized = unit.toLowerCase().replace(/s$/, '');
+    switch (normalized) {
+        case 'millisecond': return 'millisecond';
+        case 'second': return 'second';
+        case 'minute': return 'minute';
+        case 'hour': return 'hour';
+        case 'day': return 'day';
+        case 'week': return 'week';
+        case 'month': return 'month';
+        case 'year': return 'year';
+        default: return 'day';
+    }
+}
+function determineType(text) {
+    const lower = text.toLowerCase();
+    if (lower.includes('ago') || lower.includes('from now') || lower.includes('in ')) {
+        return 'relative';
+    }
+    if (lower.includes('to') || lower.includes(' - ') || lower.includes('between')) {
+        return 'range';
+    }
+    if (lower.includes('at ') || lower.includes('am') || lower.includes('pm') || /\d{1,2}:\d{2}/.test(lower)) {
+        return 'time';
+    }
+    return 'absolute';
+}
+function calculateConfidence(text) {
+    const lower = text.toLowerCase();
+    let confidence = 0.5; // Base confidence
+    // Higher confidence for specific patterns
+    if (lower.includes('tomorrow') || lower.includes('yesterday') || lower.includes('today')) {
+        confidence += 0.4;
+    }
+    if (/\d{4}/.test(text)) { // Has year
+        confidence += 0.2;
+    }
+    if (/\d{1,2}:\d{2}/.test(text)) { // Has time
+        confidence += 0.15;
+    }
+    if (lower.includes('next') || lower.includes('last')) {
+        confidence += 0.1;
+    }
+    return Math.min(1.0, confidence);
+}

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;
+}