ts-time-utils 1.0.0 → 1.1.0

package/dist/esm/index.d.ts

@@ -16,6 +16,10 @@ export { today, yesterday, tomorrow, lastNDays, nextNDays, thisWeek, lastWeek, n
 export { Duration, createDuration, isValidDuration, parseDurationString, formatDurationString, maxDuration, minDuration, sumDurations, averageDuration } from './duration.js';
 export { serializeDate, deserializeDate, createDateReviver, createDateReplacer, parseISOString, toEpochTimestamp, fromEpochTimestamp, createEpochTimestamp, toDateObject, fromDateObject, isValidISODateString, isValidEpochTimestamp, cloneDate, datesEqual, now, parseJSONWithDates, stringifyWithDates } from './serialize.js';
 export { registerLocale, getLocaleConfig, getSupportedLocales, formatRelativeTime, formatDateLocale, formatTimeLocale, formatDateTimeLocale, getMonthNames, getDayNames, getFirstDayOfWeek, isLocaleSupported, getBestMatchingLocale, detectLocale, convertRelativeTime, detectLocaleFromRelativeTime, convertFormatPattern, convertFormattedDate, convertRelativeTimeArray, compareLocaleFormats } from './locale.js';
+export { createRecurrence, getNextOccurrence, getOccurrencesBetween, isRecurrenceDate, isValidRecurrenceRule, recurrenceToString } from './recurrence.js';
+export { createCountdown, getRemainingTime, formatCountdown, isExpired, getProgressPercentage, getTimeUntil, createDeadline, type Countdown, type RemainingTime, type CountdownOptions } from './countdown.js';
+export { dateRangeOverlap, hasOverlappingRanges, mergeDateRanges, findGaps, splitRange, containsDate, getIntersection, getUnion, subtractRange, getRangeDuration, expandRange, shrinkRange, rangeContains, sortRanges } from './dateRange.js';
+export { parseNaturalDate, parseRelativePhrase, extractDatesFromText, suggestDateFromContext, type NaturalParseOptions, type ExtractedDate } from './naturalLanguage.js';
 export { MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_DAY, MILLISECONDS_PER_WEEK, MILLISECONDS_PER_MONTH, MILLISECONDS_PER_YEAR, SECONDS_PER_MINUTE, SECONDS_PER_HOUR, SECONDS_PER_DAY, SECONDS_PER_WEEK, type TimeUnit, type FormatOptions } from './constants.js';
-export type { DateInput, DateRange, ParseOptions, WorkingHoursConfig, AgeResult, ZonedTime, Interval, BenchmarkResult, RecurrencePattern, LocaleFormatOptions, BusinessConfig, DateValidator, DateTransformer, TimeUtilsError, ParseError, ValidationError, DurationUnit, DurationInput, DurationComparison, SerializationOptions, DateObject, EpochTimestamp, SupportedLocale, LocaleConfig, RelativeTimeOptions, RelativeTimeUnit } from './types.js';
+export type { DateInput, DateRange, ParseOptions, WorkingHoursConfig, AgeResult, ZonedTime, Interval, BenchmarkResult, RecurrencePattern, RecurrenceRule, RecurrenceFrequency, LocaleFormatOptions, BusinessConfig, DateValidator, DateTransformer, TimeUtilsError, ParseError, ValidationError, DurationUnit, DurationInput, DurationComparison, SerializationOptions, DateObject, EpochTimestamp, SupportedLocale, LocaleConfig, RelativeTimeOptions, RelativeTimeUnit } from './types.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -32,5 +32,13 @@ export { serializeDate, deserializeDate, createDateReviver, createDateReplacer,
 export { registerLocale, getLocaleConfig, getSupportedLocales, formatRelativeTime, formatDateLocale, formatTimeLocale, formatDateTimeLocale, getMonthNames, getDayNames, getFirstDayOfWeek, isLocaleSupported, getBestMatchingLocale, detectLocale, 
 // Conversion utilities
 convertRelativeTime, detectLocaleFromRelativeTime, convertFormatPattern, convertFormattedDate, convertRelativeTimeArray, compareLocaleFormats } from './locale.js';
+// Recurrence utilities
+export { createRecurrence, getNextOccurrence, getOccurrencesBetween, isRecurrenceDate, isValidRecurrenceRule, recurrenceToString } from './recurrence.js';
+// Countdown utilities
+export { createCountdown, getRemainingTime, formatCountdown, isExpired, getProgressPercentage, getTimeUntil, createDeadline } from './countdown.js';
+// Date range utilities
+export { dateRangeOverlap, hasOverlappingRanges, mergeDateRanges, findGaps, splitRange, containsDate, getIntersection, getUnion, subtractRange, getRangeDuration, expandRange, shrinkRange, rangeContains, sortRanges } from './dateRange.js';
+// Natural language parsing utilities
+export { parseNaturalDate, parseRelativePhrase, extractDatesFromText, suggestDateFromContext } from './naturalLanguage.js';
 // Constants and types
 export { MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_DAY, MILLISECONDS_PER_WEEK, MILLISECONDS_PER_MONTH, MILLISECONDS_PER_YEAR, SECONDS_PER_MINUTE, SECONDS_PER_HOUR, SECONDS_PER_DAY, SECONDS_PER_WEEK } from './constants.js';

package/dist/esm/naturalLanguage.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Natural language date parsing utilities
+ * Provides intelligent parsing of human-readable date strings
+ */
+/**
+ * Options for natural language parsing
+ */
+export interface NaturalParseOptions {
+    /** Reference date for relative parsing (defaults to now) */
+    referenceDate?: Date;
+    /** Preferred time for dates without time specified */
+    defaultTime?: {
+        hour: number;
+        minute: number;
+        second?: number;
+    };
+    /** Locale for language-specific parsing */
+    locale?: string;
+    /** Whether to use strict parsing */
+    strict?: boolean;
+}
+/**
+ * Extracted date information from text
+ */
+export interface ExtractedDate {
+    /** The parsed date */
+    date: Date;
+    /** The original text that was matched */
+    text: string;
+    /** Starting position in the original text */
+    index: number;
+    /** Type of date pattern matched */
+    type: 'absolute' | 'relative' | 'range' | 'time';
+    /** Confidence score (0-1) */
+    confidence: number;
+}
+/**
+ * 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 declare function parseNaturalDate(input: string, options?: NaturalParseOptions): Date | 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 declare function parseRelativePhrase(input: string, referenceDate?: Date): Date | 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 declare function extractDatesFromText(text: string, options?: NaturalParseOptions): ExtractedDate[];
+/**
+ * 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 declare function suggestDateFromContext(context: string, options?: NaturalParseOptions): Array<{
+    date: Date;
+    text: string;
+    confidence: number;
+}>;
+//# sourceMappingURL=naturalLanguage.d.ts.map

package/dist/esm/naturalLanguage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naturalLanguage.d.ts","sourceRoot":"","sources":["../../src/naturalLanguage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,sDAAsD;IACtD,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,IAAI,EAAE,IAAI,CAAC;IACX,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;IACjD,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,IAAI,GAAG,IAAI,CA8C9F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,GAAE,IAAiB,GAAG,IAAI,GAAG,IAAI,CA6DhG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,aAAa,EAAE,CAkDjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,KAAK,CAAC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAkDzD"}

package/dist/esm/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/esm/recurrence.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview Recurring events and pattern-based date generation utilities
+ * Provides RRULE-inspired recurrence patterns for creating repeating events
+ */
+import type { DateInput, RecurrenceRule } from './types.js';
+/**
+ * Creates a recurrence pattern generator
+ * @param rule - The recurrence rule defining the pattern
+ * @returns An object with methods to work with the recurrence
+ *
+ * @example
+ * ```ts
+ * // Daily recurrence
+ * const daily = createRecurrence({
+ *   frequency: 'daily',
+ *   interval: 1,
+ *   startDate: new Date('2024-01-01')
+ * });
+ *
+ * // Weekly on Monday and Wednesday
+ * const weekly = createRecurrence({
+ *   frequency: 'weekly',
+ *   interval: 1,
+ *   startDate: new Date('2024-01-01'),
+ *   byWeekday: [1, 3] // Monday = 1, Wednesday = 3
+ * });
+ *
+ * // Monthly on the 15th
+ * const monthly = createRecurrence({
+ *   frequency: 'monthly',
+ *   interval: 1,
+ *   startDate: new Date('2024-01-01'),
+ *   byMonthDay: [15]
+ * });
+ * ```
+ */
+export declare function createRecurrence(rule: RecurrenceRule): {
+    rule: RecurrenceRule;
+    getNextOccurrence: (afterDate?: DateInput) => Date | null;
+    getOccurrencesBetween: (start: DateInput, end: DateInput, limit?: number) => Date[];
+    isRecurrenceDate: (date: DateInput) => boolean;
+    getAllOccurrences: (limit?: number) => Date[];
+};
+/**
+ * Gets the next occurrence of a recurring event after a specified date
+ * @param rule - The recurrence rule
+ * @param afterDate - Date to find next occurrence after (defaults to now)
+ * @returns The next occurrence date, or null if no more occurrences
+ *
+ * @example
+ * ```ts
+ * const rule = {
+ *   frequency: 'daily',
+ *   interval: 2,
+ *   startDate: new Date('2024-01-01')
+ * };
+ *
+ * const next = getNextOccurrence(rule, new Date('2024-01-05'));
+ * // Returns Date('2024-01-07') - every other day
+ * ```
+ */
+export declare function getNextOccurrence(rule: RecurrenceRule, afterDate?: DateInput): Date | null;
+/**
+ * Gets all occurrences of a recurring event between two dates
+ * @param rule - The recurrence rule
+ * @param start - Start date of the range
+ * @param end - End date of the range
+ * @param limit - Maximum number of occurrences to return (default: 1000)
+ * @returns Array of dates that match the recurrence pattern
+ *
+ * @example
+ * ```ts
+ * const rule = {
+ *   frequency: 'weekly',
+ *   interval: 1,
+ *   startDate: new Date('2024-01-01'),
+ *   byWeekday: [1, 5] // Monday and Friday
+ * };
+ *
+ * const occurrences = getOccurrencesBetween(
+ *   rule,
+ *   new Date('2024-01-01'),
+ *   new Date('2024-01-31')
+ * );
+ * // Returns all Mondays and Fridays in January 2024
+ * ```
+ */
+export declare function getOccurrencesBetween(rule: RecurrenceRule, start: DateInput, end: DateInput, limit?: number): Date[];
+/**
+ * Checks if a specific date matches a recurrence rule
+ * @param date - The date to check
+ * @param rule - The recurrence rule
+ * @returns True if the date matches the recurrence pattern
+ *
+ * @example
+ * ```ts
+ * const rule = {
+ *   frequency: 'weekly',
+ *   interval: 1,
+ *   startDate: new Date('2024-01-01'),
+ *   byWeekday: [1] // Mondays only
+ * };
+ *
+ * isRecurrenceDate(new Date('2024-01-08'), rule); // true (Monday)
+ * isRecurrenceDate(new Date('2024-01-09'), rule); // false (Tuesday)
+ * ```
+ */
+export declare function isRecurrenceDate(date: DateInput, rule: RecurrenceRule): boolean;
+/**
+ * Validates a recurrence rule
+ * @param rule - The recurrence rule to validate
+ * @returns True if the rule is valid
+ *
+ * @example
+ * ```ts
+ * isValidRecurrenceRule({
+ *   frequency: 'daily',
+ *   interval: 1,
+ *   startDate: new Date()
+ * }); // true
+ *
+ * isValidRecurrenceRule({
+ *   frequency: 'daily',
+ *   interval: 0, // Invalid
+ *   startDate: new Date()
+ * }); // false
+ * ```
+ */
+export declare function isValidRecurrenceRule(rule: Partial<RecurrenceRule>): boolean;
+/**
+ * Converts a recurrence rule to a human-readable string
+ * @param rule - The recurrence rule
+ * @returns A human-readable description
+ *
+ * @example
+ * ```ts
+ * const rule = {
+ *   frequency: 'weekly',
+ *   interval: 2,
+ *   startDate: new Date('2024-01-01'),
+ *   byWeekday: [1, 3, 5]
+ * };
+ *
+ * recurrenceToString(rule);
+ * // "Every 2 weeks on Monday, Wednesday, Friday"
+ * ```
+ */
+export declare function recurrenceToString(rule: RecurrenceRule): string;
+//# sourceMappingURL=recurrence.d.ts.map

package/dist/esm/recurrence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurrence.d.ts","sourceRoot":"","sources":["../../src/recurrence.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAuB,MAAM,YAAY,CAAC;AAGjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc;;oCAKjB,SAAS;mCACV,SAAS,OAAO,SAAS,UAAU,MAAM;6BAE/C,SAAS;;EAqBrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAyC1F;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,SAAS,EACd,KAAK,SAAO,GACX,IAAI,EAAE,CA6BR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAW/E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAgC5E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CA6C/D"}